mcp-wms-api/CLAUDE.md

CLAUDE.md

Guide pour Claude Code (claude.ai/code) sur ce dépôt.

Avant de modifier quoi que ce soit, lisez DECISIONS.md. Il consigne les choix d'architecture et les pièges vérifiés sur un WMS réel. La plupart des comportements qui semblent bizarres y sont expliqués et sont volontaires ; les références D1, D2… de ce fichier y renvoient.

Besoin	Fichier
Installer, lancer, brancher Claude Desktop	README.md
Pourquoi le code est ainsi, pièges terrain	DECISIONS.md
Le serveur ne répond pas, lire ses logs	MONITORING.md
Ce qui reste à faire	ROADMAP.md
Superviser le projet, réviser une livraison	docs/supervision.md
Accéder aux logs du WMS	docs/logs.md
Références EasyWMS (API, entités)	docs/

---

Objet

Serveur MCP donnant à Claude un accès en lecture à un WMS EasyWMS (Mecalux) pour le debug et l'analyse. Fonctionnel et en service.

Architecture : 100 % API REST, aucun accès base de données (D1).

API	Endpoint	Usage
Query	POST {api}/QueryExecute	requêtes LINQ, lignes
Référence complète	https://<host>/ApplicationService/Help	page d'aide générée du service — la source de vérité sur les champs et les endpoints
Query scalaire	POST {api}/QueryScalarExecute	Count(), Sum() — à préférer pour « combien »
Command	POST {api}/CommandExecute	exécution de commandes WMS
Metadata	GET {api}/Metadata/Entities, GET {api}/Metadata/EntityProperties	entités interrogeables et leurs champs
GenericSearch	GET {api}/GenericSearch/Categories, POST {api}/GenericSearch/Search	recherche plein texte indexée
Application Dictionary	POST {ad}/{Type}/GetByApplication	20 types d'éléments, dont Workflow

où {api} = https://<host>/ApplicationService/api et {ad} = https://<host>/AD/api, construits depuis le host du profil actif.

Authentification : OAuth 2.0 avec refresh automatique (D2, et MONITORING.md §4).

---

Structure

src/
├── index.js                  Point d'entrée MCP : handlers list/read/call, routage
├── config/
│   └── profile-manager.js    Registre multi-profils + bascule runtime
├── resources/                Contexte en lecture seule (6 resources)
│   ├── wms-entities.js       wms://entities
│   ├── entity-schemas.js     wms://entity-schemas
│   ├── query-examples.js     wms://query-examples — exemples LINQ + recettes de diagnostic
│   ├── workflows.js          workflows://overview
│   ├── apis.js               api://catalog
│   └── logs.js               logs://guide — patterns d'erreur et scénarios de debug
├── services/                 Logique métier
│   ├── api-service.js        OAuth + client HTTP + helpers de requête (singleton)
│   ├── entity-resolver.js    Résolution Name|TableName -> TableName (D21)
│   ├── workflow-service.js   Workflows, lazy loading + cache
│   ├── ad-service.js         Application Dictionary, 20 types, cache par type
│   ├── wms-query-service.js  Construction d'expressions LINQ
│   ├── single-flight.js      Déduplication des chargements + génération (D27)
│   ├── ad-envelope.js        Enveloppe { entities } des API AD : vide anormal = erreur (D27)
│   ├── log-service.js        Lecture et recherche dans les fichiers de logs
│   └── response-limit.js     Plafond de taille commun aux outils de requête (D24)
└── tools/                    23 outils MCP
    ├── wms-query-tools.js    query_wms_entities, count_wms_entities,
    │                         get_entity_schema, search_wms_data
    ├── api-tools.js          call_query_api, execute_command
    ├── workflow-tools.js     search_workflows, get_workflow_details,
    │                         list_workflow_categories
    ├── ad-tools.js           get_application_summary, get_ad_elements,
    │                         search_ad_elements, get_ad_element_details, list_ad_types
    ├── metadata-tools.js     get_entity_metadata, generic_search
    ├── config-tools.js       get_system_parameters
    ├── profile-tools.js      list_wms_profiles, get_current_wms_profile,
    │                         switch_wms_profile
    └── log-tools.js          read_recent_logs, list_log_files, search_logs

scripts/
├── test-connection.js        Smoke test de connectivité (npm test)
└── test-ad-api.ps1           Validation curl des endpoints AD (credentials en paramètres)

docs/
└── reference-queries-api.php Client PHP d'origine — source des patterns d'API.
                              ⚠️ utilise QueryType 1 : ne pas recopier (D3)

Routage. src/index.js construit au démarrage une table nom d'outil → module depuis les listTools() des 8 modules de src/tools/ ; tools/list et le dispatch sont servis par cette même table, donc un outil listé est routé par construction (D22). Deux modules déclarant le même nom font échouer le serveur au démarrage.

---

Conventions non négociables

1. console.error() uniquement. stdout est réservé au JSON MCP ; toute écriture y casse la session Claude Desktop (D6).
2. Préfixer les logs par composant : [Server], [API], [Profile], [Workflow], [AD], [Logs], [<X>Tools]. Le tableau complet est dans MONITORING.md §2.
3. Un outil ne plante jamais le serveur. Toute erreur revient en réponse structurée { success: false, error, tool } avec isError: true — le wrapper est dans le handler tools/call de src/index.js. Les enveloppes construites localement dans src/tools/ portent le champ tool elles aussi : le wrapper ne les voit pas, et une erreur sans tool sort du contrat. Les champs supplémentaires utiles (warning de résolution, profiles, hint…) viennent après.
4. Messages d'erreur actionnables. Ils sont lus par Claude, pas par un humain : dire quoi faire ensuite (« appelez switch_wms_profile », « profils disponibles : … »).
5. Aucun accès base de données (D1).
6. 1000 lignes maximum par requête, timeout 30 s (MAX_QUERY_ROWS, QUERY_TIMEOUT).
7. Pas de concaténation LINQ à partir d'entrées utilisateur quand un filtre côté JS suffit (D11).

---

Multi-profils

Un même serveur dessert plusieurs backends WMS. Un profil = un host + des credentials + un tenant (D8).

Déclaration dans .env :

WMS_PROFILES=AD,LIMAGRAIN,EUROTRAFIC
DEFAULT_WMS_PROFILE=LIMAGRAIN

AD_HOST=10.255.255.2
AD_USERNAME=…
AD_PASSWORD=…
AD_TENANT=AD
AD_SAAS=false

Réglages partagés par tous les profils : WMS_API_AUTH, WMS_APPLICATION, WMS_API_PATH, WMS_TOKEN_PATH, WORKFLOW_API_PATH, LOGS_PATH, et les variables de cache / token / requêtes. Seul le host varie : les URL sont assemblées en https://<HOST><PATH>.

<NOM>_SAAS=true → WMS cloud : les outils de log échouent avec un message explicite (D9). Par défaut false.

LOGS_PATH accepte le placeholder {host}, substitué par le host du profil actif à chaque appel.

MAX_LOG_SEARCH_CHARS (défaut 25 000) : plafond en caractères de la réponse de search_logs — au-delà, des résultats entiers sont écartés et signalés (truncated, D24).

MAX_QUERY_RESPONSE_CHARS (défaut 25 000) : même plafond pour query_wms_entities, call_query_api et search_wms_data — au-delà, des lignes entières sont écartées et signalées (D24). count_wms_entities n'est pas concerné.

Au runtime. profile-manager est un singleton d'état global. Les services s'abonnent via onSwitch() pour invalider ce qui dépend du tenant :

Service	Réaction
api-service	resetToken()
workflow-service	clearCache()
ad-service	invalidateCache()

N'invalidez jamais ces caches à la main depuis un autre module — l'abonnement suffit (D8). Tout nouveau service portant un état lié au tenant doit s'abonner.

Sans profil actif, getCurrent() lève une erreur qui énumère les profils disponibles : c'est ainsi que Claude sait appeler switch_wms_profile.

---

Caches

TTL commun WORKFLOW_CACHE_TTL (3 600 000 ms), chargement paresseux, vidés à chaque bascule de profil (D10). Les outils AD et workflow acceptent un paramètre application (défaut : l'application du profil) — les clés de cache incluent l'application pour éviter toute pollution croisée (D26).

Cache	Granularité	Pagination
workflow-service	un par application (~4 000 EasyWMS, 153 CustomApp) + liste allégée d'Application/GetAll	WORKFLOW_PAGE_SIZE, 5000
ad-service	un par (application, type) (20 types)	AD_ELEMENT_TYPES : View 200, Workflow 5000, Resource 15000, autres 100000

Ne préchargez jamais les 9 applications : seule l'application demandée est chargée (D26). search_workflows et search_ad_elements rappellent toujours l'application interrogée et, sur résultat vide, ajoutent un hint nommant les autres — construit depuis la liste d'applications déjà en cache, jamais par un appel réseau (D26).

Les tailles de page par type viennent de l'observation des timeouts serveur — ne les augmentez pas à l'aveugle.

Les chargements sont dédupliqués par clé de cache : sous appels concurrents, une seule chaîne de fetch part par clé et les autres appelants la rejoignent (D27) — deux applications différentes se chargent toujours en parallèle. Un fetch parti avant une invalidation ne repeuple plus le cache après elle : la publication passe par un commit gardé par un compteur de génération. Ne remettez jamais d'écriture de cache dans une fonction de chargement.

Une réponse d'API AD hors enveloppe { entities: [...] } lève au lieu de passer pour un tableau vide : sinon un cache vide s'installe pour tout le TTL (D27). Un entities: [] réel reste cachable — des applications sont légitimement vides.

get_application_summary expose l'état des caches sans redémarrage.

---

Sorties bornées (D24)

Une réponse d'outil de plus de ~70 000 caractères est rejetée par le client MCP. Les outils qui peuvent dépasser ce seuil bornent et signalent : truncated: true (jamais false), hint actionnable, returned, et le total avant la coupe. Réutilisez ce vocabulaire, n'en inventez pas un second.

get_workflow_details fenêtre le blob data (la définition EasyBuilder : 71 512 caractères sur un StackerCrane, 92 362 sur un gros CST_*) : max_data_chars (défaut 20 000) et data_offset (défaut 0). Les métadonnées restent complètes, dataTotalChars est porté par toute réponse, et la tranche est verbatim — concaténer les tranches dans l'ordre des offsets reconstitue la définition à l'octet près. Ne la résumez pas, ne la « parsez » pas.

Les trois outils de requête plafonnent leur volume via src/services/response-limit.js (MAX_QUERY_RESPONSE_CHARS) : au-delà, des lignes entières sont écartées, jamais coupées au milieu. Sous le plafond, la réponse est inchangée octet pour octet — c'est la contrainte à préserver si vous y touchez.

Outil	Unité écartée	Total porté
query_wms_entities	une ligne	count (déjà présent)
call_query_api	une ligne	totalRows (ajouté à la coupe)
search_wms_data	un résultat, réparti en tourniquet entre les entités	totalFound (déjà présent)

Cas limite réel : une seule ligne Writing dépasse le plafond (95 288 caractères mesurés) — la réponse est alors returned: 0, omitted: 1, truncated: true, avec un hint qui renvoie vers Reading.

---

Écrire une requête WMS

await apiService.executeQuery(
  'Context.OutboundOrders.Where(z => z.OutboundOrderStatus == "Release").OrderBy(z => z.Id)',
  { take: 100 }
);

Répartition entre l'expression et les options — c'est la source d'erreur la plus fréquente :

Élément	Où
Where	dans l'Expression
OrderBy	dans l'Expression — obligatoire dès qu'on utilise take
Take / Skip / Select	paramètres d'API, pas dans l'expression

Autres règles :

• QueryType: 0 (Reading) par défaut : les statuts sont alors des chaînes (D3). La bascule vers Writing/Metrics passe par le paramètre query_type des outils de requête — un opt-in documenté (D25), jamais un défaut : ne recopiez aucun exemple en QueryType: 1.
• Pas de date relative. DateTime.Now, DateTime.Today, AddDays() ne sont pas traduisibles : écrire new DateTime(2026, 8, 1) (D12).
• select_expression est instable : les projections via le paramètre Select provoquent des erreurs de compilation. Interroger les lignes complètes (D13).
• Pour compter, utiliser count_wms_entities (QueryScalarExecute), pas un query suivi d'un .length.
• executeCommand prend le nom de commande tel quel : ajouter le suffixe d'assembly provoque une FileLoadException (D14).

_parseQueryResponse() gère les deux formes de réponse (tableau plat, ou { Table: { Columns, Rows } }) — ne réimplémentez pas ce décodage ailleurs.

---

Entités et éléments AD

Entités interrogeables (Query API) : entity_type accepte le nom d'entité AD (Container) ou le TableName (Containers), insensible à la casse — la résolution passe par entity-resolver.js (D21). Courantes : Products, Containers, Accounts, Suppliers, Kits, Alias (invariant, pas de pluriel), Tasks, Stocks, ProductLocations, InboundOrders, Receptions, OutboundOrders. La liste faisant foi (288 entités, toutes applications confondues) s'obtient par get_entity_metadata (API Metadata) — le catalogue de la resource wms://entities est un raccourci de confort, pas la référence.

Application Dictionary : 20 types, ~38 800 éléments (sur EasyWMS). Resource (29 374) est de loin le plus lourd ; 3 types sont valides mais vides (Dashboard, TimelineTemplate, Toggle). WorkflowAction et WritingModel ont été retirés — 404 (D17). Détail : docs/ad-api-validation.md. 9 applications AD sont déclarées ; CustomApp porte le spécifique client (workflows CST_*) et s'interroge via le paramètre application des outils AD et workflow (D26).

Paramètres système : pas d'entité CommandParameterData. La configuration se lit dans Parameter (+ DefaultValue) et ParamValue (surcharges par entrepôt, jointure sur ParameterId), fusionnées côté JS par get_system_parameters (D11).

---

Commandes

npm start                  # lancer le serveur (stdio)
npm test                   # smoke test du profil actif — lecture seule
npm test -- LIMAGRAIN      # smoke test d'un profil précis
npm test -- --all          # tous les profils
npm run build              # dist/wms-mcp-server.exe (node22-win-x64)

Le smoke test vérifie OAuth, QueryExecute, QueryScalarExecute et l'API AD, et sort en code 1 au moindre échec.

Validation des endpoints AD (PowerShell, credentials en paramètres) :

powershell -ExecutionPolicy Bypass -File scripts/test-ad-api.ps1 -WmsHost 10.255.255.2 -Username user -Password '***' -Tenant AD

---

Ajouter un outil

1. Déclarer le schéma dans listTools() du module src/tools/ concerné.
2. Traiter le cas dans son executeTool().
3. Rien à faire dans src/index.js pour un module existant : la table de routage est construite depuis listTools() (D22). Un nouveau module doit être ajouté à TOOL_MODULES.
4. Logger avec le préfixe du module.
5. Renvoyer les erreurs, ne pas les lever hors du wrapper.
6. Tester le handshake complet :

printf '%s\n%s\n%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' '{"jsonrpc":"2.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node src/index.js

---

Points ouverts

Voir ROADMAP.md : lots de correction planifiés et propositions explicitement écartées.