From 702c2ecd2ac2ad81e5b9884dae00dce2ba6b296f Mon Sep 17 00:00:00 2001 From: Arthur Ria Date: Tue, 25 Aug 2026 10:49:59 +0200 Subject: [PATCH] =?UTF-8?q?Supprime=20handoff-lot3.md=20:=20passation=20li?= =?UTF-8?q?vr=C3=A9e=20et=20r=C3=A9vis=C3=A9e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Révision du lot 3 : les sept vérifications attendues rejouées via le protocole passent (21 404 chars / 50 sur 168 paginés avec hint, plafond 25 000 respecté sur search_logs avec truncated + omitted, D23 intact, limit 200 = opt-in explicite au volume). Baseline 23/6, npm test 4/4 exit 0, diffs propres, D24 conforme aux mesures. Co-Authored-By: Claude Fable 5 --- docs/handoff-lot3.md | 175 ------------------------------------------- 1 file changed, 175 deletions(-) delete mode 100644 docs/handoff-lot3.md diff --git a/docs/handoff-lot3.md b/docs/handoff-lot3.md deleted file mode 100644 index 5f44739..0000000 --- a/docs/handoff-lot3.md +++ /dev/null @@ -1,175 +0,0 @@ -# Passation — lot 3 (L3.1, bornage des sorties volumineuses) - -Tu travailles sur `mcp-wms-api` : un serveur MCP (Node.js, CommonJS, stdio) qui -donne à Claude un accès en lecture à un WMS EasyWMS (Mecalux) via ses API REST. -Lis [../CLAUDE.md](../CLAUDE.md) et [../DECISIONS.md](../DECISIONS.md) avant de -toucher au code. - -**Mission** : borner les sorties des outils qui produisent aujourd'hui des -réponses de 50 000 à 70 000 caractères, rejetées par les clients MCP — -`get_system_parameters` et `search_logs` — avec un signal `truncated: true` -explicite plutôt qu'un rejet silencieux côté client. - -**Hors périmètre** : tout le reste de la roadmap (lot 4 en entier). En -particulier, **n'explore pas `QueryExecuteStream`** — c'est une piste long -terme consignée en L4.5, pas ce lot. Ne touche pas aux limites des outils de -requête (`MAX_QUERY_ROWS` fait déjà le travail). Ne pousse rien -(`git push` interdit), ne touche pas au `.env`, n'appelle jamais -`execute_command` (il écrit dans le WMS). - ---- - -## Contexte matériel - -- Profil de travail : `LIMAGRAIN` (par défaut), host `10.255.255.2`, tenant - `LIMAGRAI2512`, `saas=false` — les outils de logs y fonctionnent. -- **Le profil `AD` est cassé et c'est diagnostiqué — ne le réinvestigue pas** - (tenant introuvable côté STS, point ouvert de la ROADMAP). Conséquence : - `npm test -- --all` échoue sur AD ; la baseline se mesure avec `npm test` - (profil par défaut), attendu **4/4, code de sortie 0**. -- Baseline protocolaire à préserver : **23 outils**, **6 resources**, aucune - écriture sur stdout hors JSON-RPC. - -Handshake + comptages : - -```bash -printf '%s\n%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"}' '{"jsonrpc":"2.0","id":3,"method":"resources/list"}' | node src/index.js 2>/dev/null | node -e "let b='';process.stdin.on('data',d=>b+=d).on('end',()=>{for(const l of b.split('\n').filter(Boolean)){const m=JSON.parse(l);if(m.id===2)console.log('tools:',m.result.tools.length);if(m.id===3)console.log('resources:',m.result.resources.length);}});" -``` - -Mesurer la taille d'une réponse d'outil via le protocole (c'est la mesure qui -fait foi, pas une estimation) : - -```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/call","params":{"name":"NOM","arguments":{}}}' | node src/index.js 2>/dev/null | node -e "let b='';process.stdin.on('data',d=>b+=d).on('end',()=>{for(const l of b.split('\n').filter(Boolean)){const m=JSON.parse(l);if(m.id===2)console.log('chars:',m.result.content[0].text.length);}});" -``` - -## Contraintes non négociables - -1. `console.error()` uniquement — une écriture sur stdout casse Claude Desktop - (D6). -2. Un outil ne plante jamais le serveur : erreurs en réponse structurée - `{ success: false, error, tool }`, `isError: true` (wrapper de - `src/index.js`). -3. Messages d'erreur et hints actionnables : dire quoi faire ensuite. -4. Aucun accès base de données (D1). -5. **D23 : le wrapper `tools/call` valide les arguments contre les schémas.** - Tout paramètre que tu ajoutes (`limit`, `offset`…) doit être déclaré dans - l'`inputSchema` de l'outil, sinon le wrapper le rejettera comme inconnu. - C'est voulu — ne contourne pas la validation. -6. Les schémas portent `additionalProperties: false` — conserve-le. - -**Numéro de décision réservé** : **D24** = contrat de troncature (si tu actes -un contrat commun — voir L3.1c). Vérifie que D23 est bien la dernière décision -avant d'écrire. - ---- - -## Phase 0 — Confirmer les deux mesures - -Mesures du 25/08/2026 (profil `LIMAGRAIN`, via le protocole) à **confirmer** -avec la commande de mesure ci-dessus, pas à réinvestiguer : - -| Appel | Constaté | -|---|---| -| `get_system_parameters` `{}` | **70 141 caractères**, 168 paramètres, aucun `limit`/`offset` au schéma | -| `search_logs` `{"keyword":"Error"}` (défauts : `max_results` 50, `context_lines` 2) | **55 954 caractères**, 50 résultats | - -Contexte : une sortie de ~70 000 caractères a déjà été **rejetée par le client -MCP** (constat du 24/08/2026 qui a motivé ce lot). L'ordre de grandeur cible -est ~20 000–25 000 caractères par réponse ; c'est un ordre de grandeur, pas un -chiffre sacré — ce qui compte est le comportement (borné + signalé), mesuré via -le protocole. - ---- - -## L3.1a — `get_system_parameters` : pagination - -**Problème.** L'outil (`src/tools/config-tools.js`) renvoie les 168 paramètres -fusionnés d'un bloc : 70 141 caractères sans filtre. Les filtres existants -(`warehouse`, `param_class`, `search`, `only_overridden`) réduisent la sortie -mais rien ne borne le cas sans filtre. - -**À faire.** Ajouter `limit` (défaut raisonnable, ~50 — à ce volume la réponse -tient vers 21 000 caractères) et `offset` (défaut 0), **déclarés au schéma** -(contrainte 5). La réponse annonce toujours `totalParameters` (le total avant -pagination), le nombre renvoyé, et — quand la pagination a tronqué — -`truncated: true` avec un hint indiquant comment continuer (`offset` suivant) -ou réduire (`param_class`, `search`). - -**Vérification attendue** (protocole, LIMAGRAIN) : -- `{}` → taille < 25 000 caractères, 50 paramètres renvoyés, - `totalParameters: 168`, `truncated: true`, hint présent. -- `{"limit": 200}` → les 168, `truncated: false` (ou champ absent — mais alors - cohérent partout). -- `{"offset": 160}` → 8 paramètres, pas de `truncated`. -- `{"search": "CROSSDOCK"}` → comportement inchangé sur petit résultat. -- `{"lines": 5}` → toujours rejeté par le wrapper (D23 intact). - -## L3.1b — `search_logs` : garde-fou de taille - -**Problème.** `max_results` existe (défaut 50) mais ne borne pas le **volume** : -les `context_lines` multiplient la taille des résultats. Mesuré : 55 954 -caractères avec les seuls défauts. - -**À faire.** Un garde-fou sur la taille cumulée de la réponse construite -(`src/tools/log-tools.js` / `src/services/log-service.js`) : au-delà du -plafond, couper la liste des résultats — des résultats **entiers**, ne coupe -pas un résultat au milieu de ses lignes de contexte — et poser -`truncated: true` + un compte des résultats retenus/écartés + un hint -(réduire `context_lines`, affiner `keyword`, baisser `max_results`). -Plafond : constante ou variable d'environnement avec défaut (cohérent avec le -style `MAX_QUERY_ROWS`/`QUERY_TIMEOUT` dans le code existant) — documente le -choix dans le commit. - -**Pente naturelle interdite** : ne réduis pas silencieusement les défauts -(`max_results` 50, `context_lines` 2 restent tels quels) — le correctif est le -bornage signalé, pas un changement de comportement par défaut qui casserait -les usages existants. - -**Vérification attendue** (protocole, LIMAGRAIN) : -- `{"keyword":"Error"}` → taille sous le plafond choisi, `truncated: true`, - compte écarté + hint présents. -- `{"keyword":"Error","max_results":3}` → petit, pas de troncature signalée. -- Un mot-clé sans occurrence → comportement inchangé (0 résultat, pas de - `truncated`). - -## L3.1c — Cohérence du signal `truncated` - -Si tu factorises un helper de troncature commun aux deux outils, actes le -contrat en **D24** dans DECISIONS.md (forme du signal : `truncated: true`, -compte total vs renvoyé, hint actionnable). Si les deux implémentations restent -locales et divergentes, harmonise au moins les noms de champs — deux -vocabulaires pour le même concept est exactement le genre de dérive qu'on -traque en révision. `read_recent_logs` peut bénéficier du même helper si c'est -gratuit ; ne le complexifie pas pour ça. - ---- - -## Méthode - -1. Phase 0 d'abord (deux mesures, rejouées telles quelles). -2. L3.1a puis L3.1b puis L3.1c. Chaque correctif vérifié **en exécution via le - protocole** avant de passer au suivant — la taille en caractères de - `content[0].text` est la mesure qui fait foi. -3. Les schémas changent (nouveaux paramètres) : reboucler sur les 23 noms de - `tools/list` et vérifier qu'aucun ne répond `Unknown tool` (n'appelle pas - `execute_command` — vérifie sa branche statiquement), et vérifier qu'un - paramètre inconnu est toujours rejeté (D23). -4. Baseline avant/après : handshake (23/6) + `npm test` (4/4, exit 0). -5. « Non résolu » est une réponse acceptable pour une investigation time-boxée ; - une hypothèse présentée comme solution ne l'est pas. - -## Livraison - -- Un commit par correctif (L3.1a, L3.1b, L3.1c si D24), messages expliquant le - pourquoi, **mesures avant/après dans le corps du message** (tailles en - caractères, rejouées via le protocole). -- Documentation dans les mêmes commits : D24 si actée ; ROADMAP.md — retirer - L3.1 (le lot 3 devient vide : retire la section) ; CLAUDE.md ne change que si - tu ajoutes une variable d'environnement (la documenter dans la section des - réglages partagés). -- Ne pousse pas. `.env` intact. Toute anomalie hors périmètre découverte en - route : dans ROADMAP.md, pas dans le code. -- Compte-rendu final : pour chaque correctif, la vérification attendue rejouée - et son résultat **mesuré** (colle les tailles et les sorties), plus la - baseline finale.