# 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.