Arthur Ria
1a1b9ebe03
Ajoute ROADMAP.md et le relie depuis README.md et CLAUDE.md.
Origine : un rapport d'usage d'une session Cowork sur le profil LIMAGRAIN a
signalé 8 anomalies. Vérification faite contre le WMS réel, 4 bugs sont
confirmés et reproduits, dont un non signalé par le rapport.
Cause racine commune : entity_type est interpolé dans Context.{entity_type}
sans aucune validation, alors que le nom attendu est le TableName de l'API
Metadata et non le nom d'entité de l'AD. Container -> Containers, mais
Alias -> Alias : c'est un mapping, pas une règle de pluralisation. L'API
Metadata connaît 232 entités là où le MCP en expose 12 en dur, et la liste
documentée était fausse (Aliases n'existe pas).
Lot 1 (déblocage) : corps des erreurs HTTP remonté, routage des outils par
table explicite, projections de champs des workflows.
Lot 2 (fond) : résolution des entités via l'API Metadata, rejet des
paramètres inconnus.
Lot 3 : bornage des sorties volumineuses, documentation.
Trois propositions du rapport sont explicitement écartées, avec leur raison :
uniformisation des noms de paramètres, indexStatus sur generic_search, outil
dédié d'aide à la syntaxe.
CLAUDE.md : la section « Points ouverts » renvoie désormais vers la roadmap et
avertit des deux pièges non encore corrigés.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
154 lines
4.4 KiB
Markdown
154 lines
4.4 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 |
|
|
| [ROADMAP.md](ROADMAP.md) | Travaux planifiés par lot, et ce qui a été écarté |
|
|
| [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.
|