Arthur Ria
0ff44f7b78
Nouveaux documents :
- README.md : porte d'entrée humaine, absente jusqu'ici. Objet du projet,
installation, npm test, branchement Claude Desktop, ajout d'un profil WMS,
compilation de l'exécutable.
- DECISIONS.md : 20 décisions et pièges vérifiés sur un WMS réel (D1..D20),
chacun avec son pourquoi. Extrait ce qui était noyé dans CLAUDE.md :
100 % API, tenant_code OAuth, réponses {entities}, casse des propriétés,
dotenv sur stderr, dates relatives LINQ non traduisibles, absence de
CommandParameterData, etc.
- MONITORING.md : supervision du serveur MCP. Préfixes de logs, séquence
d'un démarrage sain, cycle de vie du token OAuth et ses trois filets,
état des caches, table symptôme -> cause. Une section dit explicitement
ce qui n'est pas instrumenté (ni healthcheck, ni métriques, ni alerte).
- docs/logs.md : accès aux logs du WMS. Chemins, placeholder {host},
blocage volontaire sur les profils SaaS, les trois outils, format des
lignes, limites connues.
Mises à jour :
- CLAUDE.md réécrit et aligné sur le code. Correction de l'écart le plus
gênant : le code utilise QueryType 0 (Reading), la doc annonçait 1, soit
l'inverse de ce qui fonctionne pour les comparaisons de statut par
chaîne. Corrigés également : 6 resources et non 7 (workflows://categories
n'existe pas), section .env mono-profil obsolète, références à des
fichiers de test absents, README annoncé mais inexistant. Le suivi de
projet et les checklists de phases sont retirés.
- docs/README.md : index réel du dossier. L'ancien promettait une resource
docs:// qui n'a jamais existé.
- docs/getting_started.md : avertissement en tête, c'est une capture
partielle du portail Mecalux dont les liens internes ne résolvent pas.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# WMS MCP Server
|
|
|
|
Serveur [MCP](https://modelcontextprotocol.io) qui donne à Claude un accès en
|
|
lecture à un WMS **EasyWMS** (Mecalux), pour le diagnostic et l'analyse.
|
|
|
|
Concrètement, dans Claude Desktop :
|
|
|
|
> « Combien de commandes sont bloquées en statut Release sur LIMAGRAIN ? »
|
|
> « Trouve les workflows qui touchent au réapprovisionnement. »
|
|
> « Cherche `Order 4711` dans les logs. »
|
|
> « Quels paramètres sont surchargés sur l'entrepôt 2 ? »
|
|
|
|
**Architecture : 100 % API REST.** Aucun accès direct à Oracle — voir D1 dans
|
|
[DECISIONS.md](DECISIONS.md).
|
|
|
|
---
|
|
|
|
## Ce que le serveur expose
|
|
|
|
**23 outils** répartis en 8 familles :
|
|
|
|
| Famille | Outils |
|
|
|---|---|
|
|
| Requêtes WMS | `query_wms_entities`, `count_wms_entities`, `get_entity_schema`, `search_wms_data` |
|
|
| API brutes | `call_query_api`, `execute_command` |
|
|
| Workflows | `search_workflows`, `get_workflow_details`, `list_workflow_categories` |
|
|
| Application Dictionary | `get_application_summary`, `get_ad_elements`, `search_ad_elements`, `get_ad_element_details`, `list_ad_types` |
|
|
| Métadonnées | `get_entity_metadata`, `generic_search` |
|
|
| Configuration | `get_system_parameters` |
|
|
| Profils | `list_wms_profiles`, `get_current_wms_profile`, `switch_wms_profile` |
|
|
| Logs | `read_recent_logs`, `list_log_files`, `search_logs` |
|
|
|
|
**6 resources** de contexte : `wms://entities`, `wms://entity-schemas`,
|
|
`wms://query-examples`, `workflows://overview`, `api://catalog`, `logs://guide`.
|
|
|
|
**Multi-WMS.** Plusieurs backends (clients, tenants) coexistent dans un seul
|
|
serveur ; Claude bascule à la demande avec `switch_wms_profile`.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Prérequis : Node.js 18+ et un accès réseau au WMS (VPN si nécessaire).
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
Copiez `.env.example` en `.env` et renseignez au moins un profil :
|
|
|
|
```env
|
|
WMS_API_AUTH=Basic R05BOklFNGU3aXFoZHQ=
|
|
WMS_APPLICATION=EasyWMS
|
|
WMS_API_PATH=/ApplicationService/api
|
|
WMS_TOKEN_PATH=/EasySTS/OAuth/Token
|
|
WORKFLOW_API_PATH=/AD/api
|
|
|
|
WMS_PROFILES=AD
|
|
DEFAULT_WMS_PROFILE=AD
|
|
|
|
AD_HOST=10.255.255.2
|
|
AD_USERNAME=...
|
|
AD_PASSWORD=...
|
|
AD_TENANT=AD
|
|
AD_SAAS=false
|
|
```
|
|
|
|
Vérifiez la connectivité — le test est en lecture seule :
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Sortie attendue : `4/4 tests reussis`. En cas d'échec, voir
|
|
[MONITORING.md](MONITORING.md) §7.
|
|
|
|
---
|
|
|
|
## Brancher Claude Desktop
|
|
|
|
Éditez `%APPDATA%\Claude\claude_desktop_config.json` :
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"wms": {
|
|
"command": "node",
|
|
"args": ["D:\\chemin\\vers\\mcp-wms-api\\src\\index.js"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Puis **fermez et rouvrez complètement** Claude Desktop. Les logs du serveur
|
|
apparaissent dans `%APPDATA%\Claude\logs\`.
|
|
|
|
---
|
|
|
|
## Ajouter un WMS
|
|
|
|
1. Ajoutez son nom à `WMS_PROFILES` (séparateur : virgule).
|
|
2. Définissez `<NOM>_HOST`, `<NOM>_USERNAME`, `<NOM>_PASSWORD`, `<NOM>_TENANT`.
|
|
3. Mettez `<NOM>_SAAS=true` si le WMS est hébergé dans le cloud Mecalux — les
|
|
outils de log seront alors désactivés pour ce profil, à dessein.
|
|
|
|
Les URL se construisent à partir du host : rien d'autre à dupliquer. Testez
|
|
avec `npm test -- <NOM>`.
|
|
|
|
---
|
|
|
|
## Compiler un exécutable Windows
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
Produit `dist/wms-mcp-server.exe` (~76 Mo, autonome, cible `node22-win-x64`).
|
|
|
|
**Placez le `.env` à côté de l'exe** : en mode packagé, c'est là qu'il est lu,
|
|
et aucun credential n'est embarqué dans le binaire (D7). Les avertissements
|
|
`Cannot find module '@modelcontextprotocol/sdk/…'` pendant le build sont
|
|
normaux et sans effet (D18).
|
|
|
|
Déploiement type sur la VM :
|
|
|
|
```
|
|
C:\WMS\mcp\wms-mcp-server.exe
|
|
C:\WMS\mcp\.env
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Fichier | Contenu |
|
|
|---|---|
|
|
| [CLAUDE.md](CLAUDE.md) | Architecture, inventaire des outils, conventions de code |
|
|
| [DECISIONS.md](DECISIONS.md) | **Pourquoi** le code est ainsi + pièges vérifiés en production |
|
|
| [MONITORING.md](MONITORING.md) | Superviser le serveur MCP : logs, token, caches, symptômes |
|
|
| [docs/logs.md](docs/logs.md) | Accès aux logs du WMS |
|
|
| [docs/](docs/) | Références EasyWMS (API, entités) |
|
|
|
|
---
|
|
|
|
## Sécurité
|
|
|
|
- `.env` et `dist/` sont ignorés par git — **ne les committez jamais**.
|
|
- La validation TLS est désactivée pour accepter les certificats auto-signés
|
|
des WMS on-premise (D15).
|
|
- ⚠️ L'historique git contient un ancien fichier de configuration avec des mots
|
|
de passe en clair (commit `b59cbb3`). Ces credentials sont à considérer comme
|
|
compromis — voir D20.
|