Content
# Base de données Matériaux & Alliages
Projet personnel autour d'une base de données de fiches techniques métallurgiques (alliages, nuances, éléments chimiques, normes, propriétés mécaniques). L'ensemble explore la modélisation relationnelle (MySQL) et son exposition via trois points d'accès distincts. Projet local, à visée exploratoire et technique.
Le projet se compose de trois dépôts complémentaires :
- **mysql-materials-server** — Back-end Node.js / MySQL. Gère la base de données et expose une API REST (CRUD).
- **mysql-materials-front** — Front React / React Admin. Interface d'administration CRUD des fiches techniques.
- **mysql-materials-mcp** — Serveur MCP (Node.js). Expose l'accès à la base pour interrogation via un LLM.
---
## mysql-materials-mcp
Serveur **MCP (Model Context Protocol)** qui expose la base **MySQL** du projet à un LLM (Claude Desktop). Claude peut ainsi interroger la base en langage naturel : lister les types d'alliage, filtrer les nuances par type, et récupérer le détail complet d'une nuance avec toutes ses relations.
Le serveur communique avec Claude Desktop via **stdio** (pas d'API HTTP, pas de port réseau). Il est actuellement en **lecture seule**.
---
## Stack technique
- **Node.js** (ESM, `"type": "module"`)
- **@modelcontextprotocol/sdk** — SDK officiel MCP
- **mysql2** — accès à la base MySQL (pool de connexions)
- **zod** — validation des paramètres des tools
---
## Prérequis
- **Node.js** (version récente recommandée)
- **Claude Desktop** installé
- La base **MySQL** `materials_db` doit exister et être accessible. Elle est créée et alimentée par le dépôt `mysql-materials-server` (voir son README) ; ce serveur MCP ne fait que la lire.
---
## Installation
```bash
npm install
```
---
## Configuration
Contrairement à un projet Node classique, un serveur MCP est lancé comme **sous-processus par Claude Desktop**, depuis un répertoire de travail qui n'est pas celui du projet. Un fichier `.env` local ne serait donc pas trouvé de façon fiable. Les variables d'environnement sont donc injectées **directement par Claude Desktop**, via le bloc `env` de sa configuration.
Un modèle est fourni : `claude_desktop_config.example.json`.
Il faut reporter son contenu dans le fichier de configuration de Claude Desktop, situé à :
- **Windows** : `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS** : `~/Library/Application Support/Claude/claude_desktop_config.json`
Exemple de configuration à adapter :
```json
{
"mcpServers": {
"mysql-materials-mcp": {
"command": "node",
"args": ["CHEMIN_ABSOLU/mysql-materials-mcp/server.js"],
"env": {
"DB_HOST": "localhost",
"DB_PORT": "...",
"DB_USER": "USER_READ_ONLY",
"DB_PASSWORD": "...",
"DB_NAME": "materials_db"
}
}
}
}
```
Points importants :
- **`args`** : chemin **absolu** vers `server.js`. Sous Windows, doubler les backslashes (`C:\\...`).
- Après toute modification, **redémarrer complètement Claude Desktop** (le quitter réellement, pas seulement fermer la fenêtre) pour qu'il relance le serveur avec les nouvelles variables.
- Le fichier `claude_desktop_config.json` contient les identifiants **en clair** : il vit hors du dépôt et ne doit jamais être committé. Seul le modèle `claude_desktop_config.example.json` (valeurs factices) est versionné.
### Utilisateur MySQL en lecture seule (recommandé)
Le serveur étant en lecture seule, il est recommandé de lui dédier un utilisateur MySQL avec le seul droit `SELECT`.
---
## Lancement
Le serveur est lancé automatiquement par Claude Desktop dès que celui-ci démarre (via la configuration ci-dessus). Une fois Claude Desktop redémarré, les trois tools apparaissent et sont utilisables dans une conversation.
Pour un test manuel en dehors de Claude Desktop :
```bash
npm start
# ou en développement avec rechargement auto :
npm run dev
```
---
## Structure du projet
```
.
├── server.js # Point d'entrée MCP : création du serveur, enregistrement des tools, transport stdio
├── db/
│ └── configDb.js # Pool de connexions MySQL (lecture seule)
├── tools/ # Un fichier par tool exposé à Claude
│ ├── getAlloyTypes.tool.js # Liste des types d'alliage
│ ├── getAlloyNuances.tool.js # Nuances filtrées par type d'alliage
│ └── getAlloyNuanceById.tool.js # Détail complet d'une nuance
└── claude_desktop_config.example.json # Modèle de configuration Claude Desktop
```
---
## Tools exposés
Le serveur expose trois tools, pensés pour une navigation progressive : d'abord les types, puis les nuances d'un type, puis le détail d'une nuance.
| Tool | Paramètre | Rôle |
| ------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------- |
| `get_alloy_types` | aucun | Liste tous les types d'alliage (id, nom, description). |
| `get_alloy_nuances` | `id_alloy_type` (number) | Liste les nuances (id, nom, description) d'un type donné. |
| `get_alloy_nuance_by_id` | `id` (number) | Détail complet d'une nuance : type, mesures, composition chimique, états métallurgiques, usages, normes. |
Le tool de détail effectue des **JOIN** pour renvoyer des noms lisibles (ex. « Carbon ») plutôt que des ids bruts, afin que le LLM exploite directement les données.
Les paramètres sont validés par **Zod** : Claude doit fournir le bon type (un nombre pour un id), sinon l'appel est rejeté avant d'atteindre la base.
---
## Choix techniques
- **ESM** : le SDK MCP est distribué en ESM, donc tout le projet est en `import`/`export` (`"type": "module"` dans `package.json`).
- **`console.error` et jamais `console.log`** : sur le transport stdio, la sortie standard (`stdout`) est réservée au protocole MCP. Tout message de log doit passer par `stderr`, sinon il corromprait la communication avec Claude Desktop.
- **Pool à faible limite** (`connectionLimit: 3`) : un MCP branché sur Claude Desktop dessert un seul utilisateur, pas du trafic web.
- **`multipleStatements: false`** : une seule requête par appel, plus sûr pour un serveur exposé à un LLM.
- **Requêtes préparées** (`?` + paramètres) : protection contre les injections SQL.
---
## Sécurité
- **Lecture seule** : le serveur n'expose que des `SELECT`. Un utilisateur MySQL dédié avec le seul droit `SELECT` est recommandé pour garantir cette limite au niveau de la base.
- **Identifiants hors du dépôt** : ils vivent dans la configuration locale de Claude Desktop, jamais dans le code ni dans un fichier versionné.
- **Un serveur MCP tourne comme un sous-processus avec les droits de l'utilisateur** : n'exposer que le strict nécessaire.
---
## Limites connues / pistes d'amélioration
- Lecture seule uniquement ; l'écriture via MCP est une piste en cours d'exploration.
- Trois tools de consultation ; d'autres pourraient être ajoutés (recherche par nom, filtres croisés, etc.).
- Projet local uniquement, non déployé.
