Mysql Materials

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

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 :

{
  "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 :

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é.