# Passation — lot 1 > **Comment s'en servir.** Ouvrir une nouvelle session Claude Code dans > `D:\GIT\_PERSO\mcp-wms-api` et lui donner tout ce qui suit, ou simplement : > « Lis `docs/handoff-lot1.md` et exécute-le. » > > Rédigé le 24/08/2026. Toutes les mesures citées ont été prises contre le WMS > réel (profil `LIMAGRAIN`, tenant `LIMAGRAI2512`). --- Tu interviens sur le dépôt `D:\GIT\_PERSO\mcp-wms-api` : un serveur MCP (Node.js, CommonJS) qui donne à Claude un accès en lecture à un WMS EasyWMS de Mecalux, via ses API REST uniquement. Lis `CLAUDE.md`, `DECISIONS.md` et `ROADMAP.md` avant de coder — ils contiennent les conventions et les pièges déjà constatés en production. Ta mission : implémenter le **lot 1** décrit dans `ROADMAP.md`. Trois correctifs indépendants, tous reproduits contre le WMS réel le 24/08/2026. Ne fais rien du lot 2 ni du lot 3. ## Contexte matériel Le profil `LIMAGRAIN` du `.env` local est fonctionnel et pointe sur un WMS joignable. `npm test` passe 4/4 aujourd'hui — c'est ta baseline, il doit continuer à passer. Deux commandes de vérification que tu réutiliseras : ```bash npm test ``` ```bash 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 ``` Le serveur parle JSON-RPC sur stdin/stdout. Pour appeler un outil, ajoute une ligne `{"jsonrpc":"2.0","id":N,"method":"tools/call","params":{"name":"...","arguments":{...}}}` après la notification `initialized`. ## Contraintes non négociables 1. **`console.error()` uniquement, jamais `console.log()`.** stdout est réservé au JSON du protocole MCP ; une seule écriture parasite casse la session Claude Desktop. Voir D6. 2. **Un outil ne lève jamais d'exception hors du wrapper.** Toute erreur revient en `{ success: false, error, tool }` avec `isError: true`. 3. **Les messages d'erreur sont lus par un agent, pas par un humain** : ils doivent dire quoi faire ensuite. 4. **Aucun accès base de données** (D1). Tout passe par les API REST. 5. Préfixer les logs par composant : `[Server]`, `[API]`, `[Workflow]`, `[WorkflowTools]`… 6. Ne touche pas à `.env` (ignoré par git, contient des credentials réels). --- ## Phase 0 — Vérifications avant de coder **À faire en premier, avant toute modification de code.** Ces deux points conditionnent des évolutions du lot 4 ; ils ne sont pas à implémenter maintenant, mais tu dois les vérifier pour ne pas coder le lot 1 d'une manière qui les bloquerait, et pour confirmer ou infirmer les mesures ci-dessous. Aucune modification de code dans cette phase. Uniquement des appels en lecture. ### V1 — Modèle de données : Reading ou Writing ? `QueryType` est figé à `0` (Reading) en dur dans `src/services/api-service.js` (`executeQuery` ~ligne 249, `executeScalarQuery` ~ligne 286). Aucun outil n'expose de bascule. Or `QueryContextType` a **quatre** valeurs, pas deux. Mesures déjà faites sur `LIMAGRAI2512` — confirme-les : | Valeur | Contexte | Résultat mesuré | |---|---|---| | `0` | Reading (`ApplicationReadingContext`) | opérationnel, seul utilisé | | `1` | Writing (`ApplicationWritingRepository`) | **opérationnel** — `Context.Products` répond | | `2` | DataWarehouse | non configuré : `Could not resolve serviceType 'IDataWarehouse…'` | | `3` | Metrics (`ApplicationMetricDataContext`) | contexte présent, modèle non exploré | Astuce de diagnostic à retenir : le message d'erreur **nomme le contexte** utilisé. C'est le moyen le plus rapide de savoir quel `QueryType` a réellement servi. Rappel D3 : en `QueryType: 1` les champs de statut sont des énumérations, donc `== "Release"` échoue. Le défaut devra rester `0`. ### V2 — Applications : le MCP ne voit-il que `EasyWMS` ? Constat à vérifier : `Application` vient de `WMS_APPLICATION` dans `.env`, partagé par tous les profils, sans surcharge par appel ni paramètre d'outil. `POST /AD/api/Application/GetAll` déclare **9 applications** sur le tenant `LIMAGRAI2512`. Mesures à confirmer : | Application | Workflows | Queries | Entities | |---|---:|---:|---:| | EasyWMS | 4012 | 2239 | 338 | | **CustomApp** | **153** | **54** | **11** | | AGV | 71 | 14 | 5 | | Notifications | 26 | 35 | 24 | | GalileoFaults | 9 | 20 | 24 | | Common | 1 | 7 | 25 | `CustomApp` porte le spécifique client (workflows et entités préfixés `CST_`) — exactement ce qu'on cherche en debug, et invisible aujourd'hui. Deux sous-questions, de difficulté très différente : **a) API AD.** L'application est un simple champ du payload `[application, tenant, pageSize, offset]`. Mesuré : `["CustomApp", tenant, 5, 0]` sur `/Workflow/GetByApplication` renvoie bien des workflows `CST_`. Confirme-le, et note que les caches de `ad-service` et `workflow-service` sont aujourd'hui indexés **sans** l'application : les rendre multi-applications imposera une clé de cache incluant l'application, sinon les résultats se mélangeront. **b) QueryExecute — déjà tranché, ne le réinvestigue pas.** Le champ `Application` **ne partitionne pas** le contexte de lecture : `Context.AgvTasks` (entité de l'application AGV) répond aussi bien avec `Application: "AGV"` qu'avec `Application: "EasyWMS"`. Le contexte est commun au tenant. Et les entités `CustomApp` ne sont interrogeables **dans aucun contexte** : les 11 entités `CST_` testées sous les quatre `QueryType`, au singulier et au pluriel, échouent toutes ; `Metadata/Entities` et `Metadata/EntitiesAll` renvoient 0 entité pour `CustomApp` ; aucune n'est marquée `isDataWarehouse`. Ce sont des définitions EasyBuilder sans projection requêtable. Deux conséquences à retenir, elles portent sur le **lot 2** : - la table de résolution de L2.1 devra agréger le Metadata de **toutes** les applications (`?applicationName=` par application : 232 + 20 + 6 + …), pas du seul `EasyWMS` ; - inutile d'ajouter un paramètre `application` à `QueryExecute`, il ne changerait rien. Le paramètre n'a de sens que sur les outils **AD et workflow**. Contente-toi de confirmer ces mesures si tu veux, mais **ne relance pas d'investigation dessus** : c'est du temps perdu. ### V3 — Champs de `QueryExecute` que le MCP n'envoie pas La référence officielle de l'API (`https:///ApplicationService/Help`) documente des champs inexploités. Un seul te concerne pour le lot 1 : **`ClientModule`.** Le MCP ne l'envoie pas, donc ses requêtes apparaissent dans les logs du WMS sous `Execute error. Client: GNA` — le client OAuth partagé, indistinguable du vrai client GNA. Le champ est accepté (vérifié). **Tu peux le renseigner dans le cadre de L1.1**, c'est cohérent avec l'objectif de traçabilité et ça tient en une ligne : envoyer `ClientModule: "MCP-WMS"` dans les corps de `QueryExecute` et `QueryScalarExecute`. Vérifie ensuite dans les logs du WMS (`search_logs`) que les requêtes du MCP apparaissent bien sous ce nom. Si la vérification n'est pas concluante, retire le changement et signale-le plutôt que de le laisser non vérifié. Les autres champs (`Parameters`, `CommandTimeout`, `QueryId`, `QueryExecuteStream`) sont consignés en L4.5 : **n'y touche pas**. ### Ce que tu fais de ces vérifications - Rapporte les résultats dans ton compte-rendu final, en distinguant ce que tu as mesuré de ce que tu supposes. - Mets à jour la section **Lot 4** de `ROADMAP.md` si tes mesures diffèrent, ou si tu as tranché la question (b). - **N'implémente ni V1 ni V2.** C'est le lot 4. Seul `ClientModule` (V3) entre dans ton périmètre, et seulement s'il est vérifiable. - Deux incidences concrètes sur ta façon de coder le lot 1, et elles seules : - **L1.1** : inclure `Application` et `QueryType` dans le payload rapporté par l'erreur enrichie. Sans ça, un futur bug multi-applications sera aussi opaque que les 500 d'aujourd'hui. - **L1.2** : la table de routage ne doit rien présumer de la signature des outils — ajouter demain un paramètre `application` ou `query_type` ne doit pas la toucher. --- ## L1.1 — Remonter le détail des erreurs HTTP **Problème.** Toute erreur d'API se résume aujourd'hui à `Request failed with status code 500`. Or le WMS renvoie déjà le diagnostic complet dans le corps de la réponse. Vérifié : ``` POST /QueryExecute Expression: "Context.Container.OrderBy(z => z.Id)" → 500, content-type: application/json → {"ClassName":"System.AggregateException","Message":"Compile Error: ... 'ApplicationReadingContext' ne contient pas de définition pour 'Container' ..."} ``` Ce corps est jeté par le `catch`. Une session Cowork a passé une heure sur des 500 dont la cause était écrite noir sur blanc dans la réponse HTTP. **À faire.** Dans `src/services/api-service.js`, aux blocs `catch` de `post()` (ligne ~164) et `get()` (ligne ~212), enrichir l'erreur propagée avec : - le statut HTTP, - l'URL complète et le verbe, - le payload envoyé, - le corps de la réponse, **tronqué à ~2000 caractères**, - le message d'origine. Points d'attention : - Le corps peut être un objet ou une chaîne. S'il est structuré, `Message` (et `InnerException.Message`) portent l'essentiel — privilégie-les au `JSON.stringify` intégral, qui noie l'information dans du bruit `WatsonBuckets` / `HResult`. - **Ne casse pas le retry 401 existant** : le rejeu après refresh de token doit rester intact, et une erreur pendant le rejeu doit elle aussi être enrichie. - Le point de passage est unique : ne duplique pas cette logique dans les modules `tools/`. - N'inclus jamais le token Bearer ni un mot de passe dans le message enrichi. **Vérification attendue.** Appeler `query_wms_entities` avec `entity_type: "Container"` (singulier — volontairement faux) doit faire apparaître `ApplicationReadingContext ne contient pas de définition pour 'Container'` dans la réponse de l'outil. --- ## L1.2 — Fiabiliser le routage des outils **Problème.** `src/index.js` route les appels d'outils par **préfixe de nom** dans une cascade de `else if` (handler `tools/call`, ~ligne 167). Deux outils sont listés dans `tools/list` mais n'atteignent jamais leur module : | Outil | Cause | Erreur reproduite | |---|---|---| | `get_entity_metadata` | `startsWith('get_entity_')` le capte pour `wmsQueryTools`, dont la branche vient **avant** la sienne | `Unknown WMS query tool: get_entity_metadata` | | `list_log_files` | la branche logs teste `includes('_logs')`, or le nom contient `_log_files` | `Unknown tool: list_log_files` | **À faire.** Remplacer la cascade par une **table explicite `nom d'outil → module`**, construite au démarrage en parcourant les `listTools()` des 8 modules de `src/tools/`. Le dispatch devient un simple lookup. Exigences : - Si deux modules déclarent le même nom d'outil, **échouer au démarrage** avec un message nommant les deux modules — c'est un bug de développement, pas un cas d'exécution. - Un outil listé est un outil routé, par construction : c'est tout l'intérêt du changement. - Le wrapper d'erreur existant du handler `tools/call` doit être conservé tel quel. - Les 23 outils doivent rester exposés, aux mêmes noms. Ce n'est pas une refonte de l'API : aucun renommage. **Vérification attendue.** `get_entity_metadata` et `list_log_files` répondent tous les deux, et un `tools/list` renvoie toujours 23 outils. Vérifie aussi que rien n'a régressé sur les 21 autres : chaque nom listé doit résoudre vers un module. --- ## L1.3 — Corriger les projections de champs des workflows **Problème.** L'API Application Dictionary renvoie ses champs **en minuscules**. Les clés réelles d'un objet workflow, relevées en direct : ``` $id, validFrom, validTo, versionId, version, lockInfo, id, name, commonInfo, applicationName, dataType, data ``` Deux endroits supposent autre chose : 1. `src/tools/workflow-tools.js`, fonction `searchWorkflows` (~ligne 110) : projette `w.Id`, `w.Code`, `w.Name`, `w.Category`, `w.Description`, `w.Version`, `w.Created`, `w.Modified`. Tous valent `undefined`, `JSON.stringify` les supprime — d'où **50 objets vides `{}`** alors que `count` est correct. 2. `src/services/workflow-service.js` (~lignes 123, 167, 187) : lit `w.category || w.Category`. Ces deux clés n'existent pas. Conséquence mesurée : `list_workflow_categories` renvoie **0 catégorie** et `getWorkflowStats()` classe les **4012** workflows en `Uncategorized`. C'est une application incomplète du piège D5 : le service gère bien la double casse pour `name`/`id` (d'où un filtrage correct), mais la projection du tool et la notion de catégorie ont été écrites sur des champs imaginaires. **À faire.** - Aligner la projection de `searchWorkflows` sur les clés réelles, en conservant le repli `w.id || w.Id` de D5. - `Code`, `Description`, `Created`, `Modified` n'existent dans **aucune** casse : ne les projette pas plutôt que d'exposer des `null` permanents. Si tu juges qu'un équivalent existe dans `commonInfo`, inspecte-le d'abord et décide sur pièces. - Pour la catégorie : le seul champ approchant est `applicationName`, **mais il vaut `EasyWMS` pour tous les workflows**. La notion de catégorie n'a donc aucun support dans les données. Traite-la honnêtement — mappe sur `applicationName` en l'assumant, ou retire la notion — mais **n'invente pas une taxonomie** en dérivant des catégories d'un préfixe de nom. Le paramètre `category` de `search_workflows` doit rester cohérent avec ce que tu décides, et `list_workflow_categories` ne doit pas mentir sur ce qu'il renvoie. - Vérifie au passage `get_workflow_details` : il renvoie l'objet brut, il ne devrait pas être affecté — confirme-le plutôt que de le supposer. **Vérification attendue.** `search_workflows({query: "stacker"})` renvoie des objets peuplés avec au minimum `id` et `name` (attendu : des noms comme `StackerCrane_SortPickingTasksBalancingOutputs_PR`). `list_workflow_categories` renvoie un résultat cohérent avec la réalité des données, et non `0`. --- ## Méthode Fais la **phase 0** d'abord, sans toucher au code. Puis les trois correctifs dans l'ordre : L1.1 en premier, parce qu'il rend les deux autres plus faciles à diagnostiquer. **Vérifie contre le WMS réel, pas seulement par lecture de code.** Chaque correctif a une vérification attendue décrite ci-dessus ; exécute-la. Les appels concernés sont en lecture seule, aucun risque d'écriture WMS. Si un point ne peut pas être vérifié, dis-le explicitement plutôt que de le déclarer fait. Avant de conclure, relance la baseline complète : - `npm test` → 4/4, - handshake MCP → 23 outils, 6 resources, - les trois vérifications attendues ci-dessus. ## Livraison - Un commit par correctif (L1.1, L1.2, L1.3), messages en français, pour que chacun soit revertable seul. Stage chemin par chemin, **pas de `git add -A`**. - Termine les messages de commit par `Co-Authored-By: Claude Opus 5 `. - **Ne pousse pas** — la branche `main` a un remote, le push est une décision du propriétaire du dépôt. - Mets à jour `ROADMAP.md` : retire le lot 1 une fois livré. - Ajoute à `DECISIONS.md` l'entrée **D22** (routage par table explicite : pourquoi le routage par préfixe a été abandonné, avec les deux collisions comme preuve). Suis le format des entrées existantes. **D21 est réservée au lot 2, ne l'utilise pas.** - Si tu découvres une anomalie hors périmètre, **ne la corrige pas** : ajoute-la à `ROADMAP.md` et signale-la dans ton compte-rendu. Dans ton compte-rendu final, indique ce que tu as vérifié en exécution et ce que tu n'as pas pu vérifier.