@imenam/mcp-design 1.0.7 → 1.0.8

package/README.md

@@ -167,6 +167,19 @@ Le texte n'est **jamais re-wrappé automatiquement** : seuls les `\n` explicites
 
 `lineHeight` est une **distance en pixels entre deux lignes de base**, pas un multiplicateur de `fontSize` : avec `fontSize: 64`, on écrit `76`, pas `1.2`. C'est l'unité que les agents emploient spontanément, et la seule qui se lise dans la même échelle que le reste. Une valeur sous 4 est donc refusée à l'écriture avec un message explicite, et les fichiers écrits avant ce changement sont convertis à la lecture (`ratio x fontSize`) par [`src/core/migrate.ts`](src/core/migrate.ts). Champ omis = `fontSize x 1.35`.
 
+#### La boîte d'un texte épouse son texte
+
+Le bloc de lignes est **centré verticalement dans la boîte** du nœud : c'est ce qui permet de centrer un libellé dans un bouton sans calculer de décalage. Encore faut-il que la boîte soit celle qu'on croit — une hauteur par défaut plus grande que le texte le fait descendre sous le point posé.
+
+Donc : **un nœud `text` créé sans `height` prend la hauteur exacte de son texte** (`lignes x lineHeight`). Le centrage n'a alors plus rien à décaler, et la première ligne commence bien à `y`, à gauche de `x`. Ajouter une ligne agrandit la boîte au lieu de la faire déborder : une boîte qui épousait son texte continue de l'épouser, à chaque changement de `text`, `fontSize` ou `lineHeight`, à l'écriture par l'agent comme à l'édition dans la GUI.
+
+Une hauteur **explicite**, elle, n'est jamais retouchée — c'est le geste qui dit « centre ce libellé » :
+
+```jsonc
+{ "type": "text", "x": 40, "y": 120, "text": "Titre", "fontSize": 32 }          // boîte = 43.2px, texte posé à y
+{ "type": "text", "x": 40, "y": 100, "height": 26, "text": "OK", "fontSize": 12 } // libellé centré dans son bouton
+```
+
 ### Groupes réutilisables
 
 Quand un même bloc revient plusieurs fois — une carte, une ligne de liste, un bouton —, il ne se recopie pas : il se **construit une fois** en groupe, puis s'**instancie**. Une `instance` ne stocke aucun contenu, seulement l'identifiant du groupe qu'elle reproduit ; le sous-arbre est reconstitué au rendu. Éditer le groupe met donc à jour **toutes** ses instances d'un coup, et un bloc répété reste une seule chose à lire et à modifier. C'est le fonctionnement d'un composant principal dans Figma.
@@ -208,8 +221,12 @@ Un lot est intégralement validé avant la moindre écriture : une entrée inval
 |---|---|
 | `get_changes` | Liste tout ce qui a été ajouté, modifié, supprimé ou réordonné depuis la dernière baseline, champ par champ (`x: 40 -> 240`). |
 | `mark_synced` | Fige l'état courant comme nouvelle baseline. |
-| `export_design` | Rend la planche en `html`, `jsx`, `svg`, `json` ou `summary`. `output_path` écrit dans un fichier au lieu de renvoyer le contenu. |
-| `screenshot_design` | Rasterise la planche en PNG et le renvoie **en image** à l'agent. `node_id` cadre la capture sur un groupe (ou n'importe quel élément), `scale` zoome, `padding` ajoute de la marge, `output_path` écrit un `.png` au lieu de renvoyer l'image. |
+| `export_design` | Rend la planche en `html`, `jsx`, `svg`, `json` ou `summary`. `destination_path` + `filename` écrivent un fichier **sur la machine de l'agent** au lieu de renvoyer le contenu. |
+| `screenshot_design` | Rasterise la planche en PNG et le renvoie **en image** à l'agent. `node_id` cadre la capture sur un groupe (ou n'importe quel élément), `scale` zoome, `padding` ajoute de la marge, `destination_path` + `filename` écrivent un `.png` **sur la machine de l'agent** au lieu de renvoyer l'image. |
+
+> **Où le fichier est écrit.** `destination_path` est un **dossier absolu** sur la machine de l'agent, `filename` le nom que le fichier y prend. Omis, les deux outils se comportent comme avant : le contenu (ou l'image) revient dans la réponse, sans fichier.
+>
+> En stdio, ce MCP tourne à côté de l'agent et écrit lui-même. Derrière [`@imenam/mcp-http-gateway`](https://www.npmjs.com/package/@imenam/mcp-http-gateway), il tourne sur la machine du gateway et ne peut pas atteindre le disque de l'agent : il déclare alors la paire `destination_path` / `destination_relay`, renvoie les octets, et le relais — qui tourne, lui, sur la machine de l'agent — les y écrit. `destination_relay` est rempli par le relais, jamais par l'agent, et cette voie exige `GATEWAY_INLINE_WRITE_ROOTS` dans le bloc `env` du relais.
 
 **`get_changes` n'acquitte jamais ce qu'il montre.** Seul `mark_synced` déplace la baseline, et il ne doit être appelé qu'une fois les modifications réellement reportées dans le code. Un simple appel de lecture ne peut donc pas faire disparaître un diff que l'agent n'a pas encore traité.
 
@@ -246,7 +263,7 @@ Trois colonnes : la liste des planches, le canvas, l'inspecteur et les calques.
 - **Outils** — sélection, rectangle, ellipse, ligne, texte, icône. Glisser pour dimensionner, cliquer pour poser à la taille par défaut. L'outil icône ouvre d'abord son sélecteur : poser une icône suppose d'avoir choisi laquelle.
 - **Édition** — déplacement au glisser, 8 poignées de redimensionnement (2 extrémités pour une ligne), sélection multiple au rectangle d'encadrement ou au Maj+clic.
 - **Groupes** — `Ctrl+G` groupe la sélection, `Ctrl+Maj+G` la dissout. Un clic dans le canvas sélectionne le **groupe le plus haut** ; `Alt+clic` vise l'élément exact à l'intérieur. Déplacer un groupe déplace tout son contenu.
-- **Texte** — double-clic pour éditer en place, avec la même métrique qu'au rendu final.
+- **Texte** — double-clic pour éditer en place, avec la même métrique qu'au rendu final. Une boîte à la taille de son texte le reste : ajouter une ligne l'agrandit d'autant.
 - **Inspecteur** — position, taille, rotation, opacité, couleurs, épaisseur, arrondi, contenu, taille et graisse de police, interligne (en px), alignement, choix de l'icône. Pour un groupe, la taille est affichée en lecture seule puisqu'elle suit son contenu ; pour une icône, un seul champ de taille, puisqu'elle est carrée.
 - **Calques** — arbre repliable, ordre d'empilement, sélection, montée/descente d'un cran.
 

package/dist/shared/node-defaults.d.ts

@@ -1,4 +1,4 @@
-import type { RenderNode } from "./render.js";
+import { type RenderNode } from "./render.js";
 /**
  * Valeurs par défaut et champs autorisés par type de noeud.
  *

package/dist/shared/node-defaults.js

@@ -1,3 +1,4 @@
+import { defaultLineHeight } from "./render.js";
 import { DEFAULT_ICON_STROKE_WIDTH, ICON_GRID } from "./icons/index.js";
 export const NODE_KINDS = ["rect", "ellipse", "line", "text", "icon", "group", "instance"];
 /** Types que l'utilisateur peut dessiner directement ; un groupe se cree a partir d'une selection. */
@@ -8,7 +9,11 @@ export const NODE_DEFAULTS = {
     line: { width: 200, height: 0, stroke: "#1a1a18", strokeWidth: 2 },
     text: {
         width: 260,
-        height: 40,
+        // Une ligne : la boîte par défaut épouse le texte par défaut. Toute autre
+        // hauteur ferait descendre la première ligne sous le point posé, puisque le
+        // bloc de lignes est centré dans sa boîte. Un texte créé sans hauteur la
+        // recalcule de toute façon sur son propre contenu.
+        height: defaultLineHeight(24),
         text: "Texte",
         color: "#1a1a18",
         fontSize: 24,
@@ -16,8 +21,9 @@ export const NODE_DEFAULTS = {
         fontWeight: 400,
         fontStyle: "normal",
         textAlign: "left",
-        // En pixels, comme x/y/fontSize — jamais un multiplicateur.
-        lineHeight: 32,
+        // `lineHeight` n'a volontairement pas de valeur par défaut : figée, elle
+        // rendrait un texte de 64px sur un interligne de 32. Absente, elle suit la
+        // taille de police (fontSize x 1.35), comme l'annonce sa documentation.
     },
     // Taille de la grille de Lucide : une icone posee sans consigne rend au
     // format pour lequel son trace a ete dessine.

package/dist/shared/node-fields.js

@@ -22,7 +22,10 @@ export const NODE_FIELD_DOCS = {
     width: "Width of the bounding box, in pixels. On a line, the horizontal delta from start to end — it may be negative. " +
         "On a group, derived from the content and read-only.",
     height: "Height of the bounding box, in pixels. On a line, the vertical delta from start to end — it may be negative. " +
-        "On a group, derived from the content and read-only.",
+        "On a group, derived from the content and read-only. " +
+        "On a TEXT node, leave it out: the box then takes the exact height of the text (lines x lineHeight), " +
+        "so the first line starts at y. Set it only to centre a label inside a container — give the text node " +
+        "the container's y and height, and the block of lines is centred in it.",
     rotation: "Rotation in degrees, clockwise, around the centre of the bounding box. 0 = upright.",
     opacity: "Opacity, from 0 (fully transparent) to 1 (fully opaque).",
     fill: 'CSS colour filling the interior, e.g. "#ffffff" or "rgba(0,0,0,0.4)". rect, ellipse and icon. On an icon it is "none" by default — the shape is drawn by its stroke.',
@@ -42,7 +45,8 @@ export const NODE_FIELD_DOCS = {
         "node to read and to change. Whenever the same block appears more than once (cards, list rows, menu items, " +
         "buttons), build it once as a group and add instances of it instead of duplicating it. " +
         "Change this field to swap an instance over to another group; use detach_instances when one copy must diverge.",
-    text: "Text content. It is NEVER auto-wrapped: only explicit \\n characters start a new line.",
+    text: "Text content. It is NEVER auto-wrapped: only explicit \\n characters start a new line. " +
+        "A box that hugs its text keeps hugging it: adding a line grows the box instead of overflowing it.",
     color: "CSS colour of the text.",
     fontSize: "Font size, in pixels (same meaning as the CSS font-size property).",
     fontFamily: 'CSS font stack, e.g. "Inter, system-ui, sans-serif".',

package/dist/shared/render.d.ts

@@ -81,6 +81,24 @@ export declare function textMetrics(node: RenderNode): {
 };
 /** Hauteur minimale nécessaire pour afficher tout le texte du noeud. */
 export declare function measuredTextHeight(node: RenderNode): number;
+/**
+ * Vrai quand la boîte épouse déjà exactement son texte.
+ *
+ * C'est le signe qu'aucune hauteur n'a été voulue pour elle-même : la boîte
+ * suit son contenu, et doit continuer à le suivre quand le texte change. Une
+ * hauteur choisie (un libellé calé sur la hauteur de son bouton) ne vérifie pas
+ * cette égalité et n'est donc jamais réajustée.
+ */
+export declare function hugsText(node: RenderNode): boolean;
+/**
+ * Le noeud, avec la hauteur qui épouse son texte.
+ *
+ * Une boîte à la taille de son texte le place de fait en haut à gauche : le
+ * centrage vertical n'a plus rien à décaler. C'est ce qu'attend qui pose un
+ * texte sans penser à sa boîte ; un conteneur qui veut centrer son libellé,
+ * lui, donne une hauteur explicite.
+ */
+export declare function withFittedTextHeight<T extends RenderNode>(node: T): T;
 /**
  * Transform SVG d'un groupe : translation vers son origine, puis rotation
  * autour du centre de son contenu (exprime dans l'espace local du groupe).

package/dist/shared/render.js

@@ -98,6 +98,28 @@ export function measuredTextHeight(node) {
     const { lineStep } = textMetrics(node);
     return Math.max(lineStep, textLines(node).length * lineStep);
 }
+/**
+ * Vrai quand la boîte épouse déjà exactement son texte.
+ *
+ * C'est le signe qu'aucune hauteur n'a été voulue pour elle-même : la boîte
+ * suit son contenu, et doit continuer à le suivre quand le texte change. Une
+ * hauteur choisie (un libellé calé sur la hauteur de son bouton) ne vérifie pas
+ * cette égalité et n'est donc jamais réajustée.
+ */
+export function hugsText(node) {
+    return Math.abs(Math.abs(node.height) - measuredTextHeight(node)) < 0.5;
+}
+/**
+ * Le noeud, avec la hauteur qui épouse son texte.
+ *
+ * Une boîte à la taille de son texte le place de fait en haut à gauche : le
+ * centrage vertical n'a plus rien à décaler. C'est ce qu'attend qui pose un
+ * texte sans penser à sa boîte ; un conteneur qui veut centrer son libellé,
+ * lui, donne une hauteur explicite.
+ */
+export function withFittedTextHeight(node) {
+    return { ...node, height: measuredTextHeight(node) };
+}
 function shapeAttributes(node) {
     const parts = [];
     if (node.type !== "line" && node.type !== "text") {

package/dist/src/core/node-factory.js

@@ -1,5 +1,6 @@
 import { DesignNodeSchema } from "../../shared/schemas/design.schema.js";
 import { GROUP_DERIVED_FIELDS, NODE_DEFAULTS, NODE_GEOMETRY_FIELDS, NODE_STYLE_FIELDS, SIZE_DERIVED_KINDS, clampNodeSize, defaultNodeName, } from "../../shared/node-defaults.js";
+import { hugsText, measuredTextHeight } from "../../shared/render.js";
 import { CORE_ICONS, hasIcon, iconCount } from "../../shared/icons/index.js";
 import { suggestIcons } from "../../shared/icons/search.js";
 import { shortId } from "./ids.js";
@@ -106,6 +107,14 @@ export function buildNode(input, existingIds, index) {
     const size = clampNodeSize(type, Number(draft.width), Number(draft.height));
     draft.width = size.width;
     draft.height = size.height;
+    // Sans hauteur demandée, la boîte d'un texte est celle de son texte : le bloc
+    // de lignes, centré dans une boîte à sa taille, se pose alors exactement au
+    // point donné — ce que l'appelant attend quand il n'a parlé que de x et y.
+    // Après le clamp, donc : ce plancher garde une boîte dessinée sélectionnable,
+    // il n'a pas à gonfler une boîte qui n'a jamais été dimensionnée à la souris.
+    if (type === "text" && input.height === undefined) {
+        draft.height = measuredTextHeight(draft);
+    }
     const parsed = DesignNodeSchema.safeParse(draft);
     if (!parsed.success) {
         throw new DesignError(`Invalid node: ${parsed.error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join("; ")}`);
@@ -131,6 +140,12 @@ export function applyPatch(node, patch) {
         if (patch[field] !== undefined)
             next[field] = patch[field];
     }
+    // Une boîte qui épousait son texte continue de l'épouser : rallonger le texte
+    // d'une ligne agrandit la boîte au lieu de la faire déborder. Une hauteur
+    // choisie — ou redonnée dans ce patch — reste intacte.
+    if (node.type === "text" && patch.height === undefined && hugsText(node)) {
+        next.height = measuredTextHeight(next);
+    }
     if (node.type === "icon" && patch.icon !== undefined)
         next.icon = requireIconName(patch.icon);
     // Changer le lien echange l'instance de composant, comme un "swap instance".

package/dist/src/index.js

@@ -34,6 +34,7 @@ import { getChanges } from "./tools/get-changes.js";
 import { markSynced } from "./tools/mark-synced.js";
 import { exportDesignTool } from "./tools/export-design.js";
 import { screenshotDesignTool } from "./tools/screenshot-design.js";
+import { RELAY_SHAPE_DESCRIPTIONS } from "./tools/relay.js";
 import { reorderNodesTool } from "./tools/reorder-nodes.js";
 import { searchIconsTool, DEFAULT_ICON_RESULTS, MAX_ICON_RESULTS } from "./tools/search-icons.js";
 const __filename = fileURLToPath(import.meta.url);
@@ -335,6 +336,8 @@ const NODE_FIELDS_DOC = "Every length is in PIXELS (x, y, width, height, strokeW
     "Fields accepted per type — rect: fill, stroke, strokeWidth, radius; ellipse: fill, stroke, strokeWidth; " +
     "line: stroke, strokeWidth (the line goes from (x, y) to (x + width, y + height)); " +
     "text: text, color, fontSize, fontFamily, fontWeight, fontStyle, textAlign, lineHeight; " +
+    "a text node given no height takes the exact height of its text, so its first line starts at y — " +
+    "pass a height only to centre a label inside a container (same y and height as the container); " +
     "icon: icon (required — the name of the drawing), fill, stroke, strokeWidth; " +
     "instance: componentId (required — the id of the group it mirrors); nothing else, its look comes from that group. " +
     "Any field left out falls back to a sensible default, so a node can be created from its type alone.";
@@ -688,13 +691,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "export_design",
-            description: "Render a design for integration. html = absolutely positioned divs + CSS (best starting point for real code), jsx = the same as a React component, svg = faithful preview, json = raw nodes, summary = textual inventory. Provide output_path to write to a file instead of returning the content.",
+            description: "Render a design for integration. html = absolutely positioned divs + CSS (best starting point for real code), jsx = the same as a React component, svg = faithful preview, json = raw nodes, summary = textual inventory. Provide destination_path and filename to write a file on the agent machine instead of returning the content.",
             inputSchema: {
                 type: "object",
                 properties: {
                     design_id: { type: "string", description: DESIGN_ID_DOC },
                     format: { type: "string", enum: [...EXPORT_FORMATS], description: "Output format (default html)." },
-                    output_path: { type: "string", description: "Absolute path to write the export to. When omitted, the content is returned directly." },
+                    destination_path: {
+                        type: "string",
+                        description: `${RELAY_SHAPE_DESCRIPTIONS.destination_path}. When omitted, the content is returned directly instead of being written.`,
+                    },
+                    filename: { type: "string", description: `${RELAY_SHAPE_DESCRIPTIONS.filename}. Required when destination_path is provided.` },
+                    destination_overwrite: { type: "boolean", description: RELAY_SHAPE_DESCRIPTIONS.destination_overwrite },
+                    destination_relay: { type: "boolean", description: RELAY_SHAPE_DESCRIPTIONS.destination_relay },
                 },
                 required: ["design_id"],
             },
@@ -703,7 +712,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             name: "screenshot_design",
             description: "Render a design to a PNG image and look at it. Use it to check what the design actually looks like — proportions, overlaps, contrast, alignment — instead of inferring it from coordinates. " +
                 "Pass node_id to frame the capture on a single group (or any element) rather than the whole artboard. " +
-                "The image is returned inline; provide output_path to write a .png file instead.",
+                "The image is returned inline; provide destination_path and filename to write a .png file on the agent machine instead.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -720,10 +729,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: "number",
                         description: "Margin in design pixels around the captured node (default 16, ignored for a full-artboard capture).",
                     },
-                    output_path: {
+                    destination_path: {
                         type: "string",
-                        description: "Absolute path of a .png file to write. When omitted, the image is returned inline.",
+                        description: `${RELAY_SHAPE_DESCRIPTIONS.destination_path}. When omitted, the image is returned inline instead of being written.`,
                     },
+                    filename: { type: "string", description: "Name of the .png file to create. Required when destination_path is provided. Must not contain path separators." },
+                    destination_overwrite: { type: "boolean", description: RELAY_SHAPE_DESCRIPTIONS.destination_overwrite },
+                    destination_relay: { type: "boolean", description: RELAY_SHAPE_DESCRIPTIONS.destination_relay },
                 },
                 required: ["design_id"],
             },

package/dist/src/tools/export-design.d.ts

@@ -1,3 +1,3 @@
 import type { DesignStore } from "../core/design-store.js";
-import { type ToolResult } from "./types.js";
-export declare function exportDesignTool(store: DesignStore, args: Record<string, unknown> | undefined): ToolResult;
+import { type FileToolResult } from "./types.js";
+export declare function exportDesignTool(store: DesignStore, args: Record<string, unknown> | undefined): FileToolResult;

package/dist/src/tools/export-design.js

@@ -1,7 +1,13 @@
-import fs from "fs";
-import path from "path";
 import { EXPORT_FORMATS, exportDesign as render } from "../core/export.js";
+import { deliverFile } from "./relay.js";
 import { requireString, textResult } from "./types.js";
+const MIME_BY_FORMAT = {
+    html: "text/html",
+    jsx: "text/jsx",
+    svg: "image/svg+xml",
+    json: "application/json",
+    summary: "text/plain",
+};
 export function exportDesignTool(store, args) {
     const id = requireString(args, "design_id");
     const format = (args?.format ?? "html");
@@ -10,12 +16,25 @@ export function exportDesignTool(store, args) {
     }
     const design = store.get(id);
     const content = render(design, format);
-    const outputPath = typeof args?.output_path === "string" ? args.output_path.trim() : "";
-    if (outputPath) {
-        const target = path.resolve(outputPath);
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.writeFileSync(target, content, "utf-8");
-        return textResult(`Design "${design.name}" exported as ${format} to ${target} (${content.length} characters).`);
+    const destination = typeof args?.destination_path === "string" ? args.destination_path.trim() : "";
+    if (!destination) {
+        return textResult(content);
     }
-    return textResult(content);
+    // Le fichier part vers la machine de l'agent : ici on ne fait que produire les octets,
+    // `deliverFile` décide s'ils s'écrivent sur ce disque ou voyagent jusqu'au relais.
+    const blocks = deliverFile(Buffer.from(content, "utf-8"), MIME_BY_FORMAT[format] ?? "text/plain", {
+        destination_path: destination,
+        filename: requireString(args, "filename"),
+        destination_overwrite: args?.destination_overwrite === true,
+        destination_relay: args?.destination_relay === true,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Design "${design.name}" exported as ${format} (${content.length} characters).`,
+            },
+            ...blocks,
+        ],
+    };
 }

package/dist/src/tools/relay.d.ts

@@ -0,0 +1,27 @@
+export declare const RELAY_SHAPE_DESCRIPTIONS: {
+    readonly destination_path: "ABSOLUTE path of the destination DIRECTORY on the agent machine. It is created if missing, and the file keeps the name given in filename";
+    readonly filename: "Name of the file to create, extension included (e.g. 'design.html'). Must not contain path separators";
+    readonly destination_overwrite: "Replace the destination file if it already exists. Defaults to false";
+    readonly destination_relay: "Filled in by the mcp-http-gateway relay, never by the agent. Signals that the destination lives on another machine and that the file content must travel in the response";
+};
+export interface DeliveryTarget {
+    destination_path: string;
+    filename: string;
+    destination_overwrite?: boolean;
+    destination_relay?: boolean;
+}
+import type { ResourceBlock } from "./types.js";
+type ContentBlock = {
+    type: "text";
+    text: string;
+} | ResourceBlock;
+/**
+ * Livre un fichier produit par le MCP, du bon côté de la chaîne.
+ *
+ * Renvoie les blocs de contenu à faire figurer dans le résultat de l'outil : un bloc
+ * `resource` que le relais interceptera et retirera, ou une simple confirmation quand
+ * l'écriture a eu lieu ici. Toute impossibilité est une erreur franche : mieux vaut un
+ * fichier perdu qu'un fichier écrit sur la mauvaise machine.
+ */
+export declare function deliverFile(data: Buffer, mimeType: string, target: DeliveryTarget): ContentBlock[];
+export {};

package/dist/src/tools/relay.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+// Un fichier produit par ce MCP n'a aucun moyen d'atteindre la machine de l'agent quand
+// le MCP tourne derrière mcp-http-gateway : le protocole n'offre au serveur aucune
+// primitive pour y écrire. La convention du relais règle ça — dès qu'un outil déclare la
+// paire `destination_path` / `destination_relay`, le relais retient la destination, pose
+// `destination_relay`, et écrit lui-même les octets qu'on lui renvoie.
+//
+// Ici, on ne sait pas si un relais est dans la chaîne : `destination_relay` le dit. Posé,
+// on renvoie le contenu ; absent, les deux machines n'en font qu'une et on écrit nous-même.
+/** Plafond de ce qui peut être encodé dans une réponse d'outil. Le relais applique sa
+ *  propre limite, configurable ; celle-ci n'existe que pour qu'un fichier démesuré
+ *  échoue proprement ici plutôt qu'en épuisant la mémoire pendant l'encodage base64. */
+const RELAY_MAX_BYTES = 32 * 1024 * 1024;
+export const RELAY_SHAPE_DESCRIPTIONS = {
+    destination_path: "ABSOLUTE path of the destination DIRECTORY on the agent machine. It is created if missing, and the file keeps the name given in filename",
+    filename: "Name of the file to create, extension included (e.g. 'design.html'). Must not contain path separators",
+    destination_overwrite: "Replace the destination file if it already exists. Defaults to false",
+    destination_relay: "Filled in by the mcp-http-gateway relay, never by the agent. Signals that the destination lives on another machine and that the file content must travel in the response",
+};
+/**
+ * Livre un fichier produit par le MCP, du bon côté de la chaîne.
+ *
+ * Renvoie les blocs de contenu à faire figurer dans le résultat de l'outil : un bloc
+ * `resource` que le relais interceptera et retirera, ou une simple confirmation quand
+ * l'écriture a eu lieu ici. Toute impossibilité est une erreur franche : mieux vaut un
+ * fichier perdu qu'un fichier écrit sur la mauvaise machine.
+ */
+export function deliverFile(data, mimeType, target) {
+    const name = path.basename(target.filename);
+    if (name !== target.filename || name === "." || name === "..") {
+        throw new Error(`filename must be a bare file name, without path separators: ${target.filename}`);
+    }
+    if (data.length > RELAY_MAX_BYTES) {
+        throw new Error(`File too large to transfer: ${data.length} bytes, the limit is ${RELAY_MAX_BYTES}.`);
+    }
+    // Le relais tourne sur la machine de l'agent et a retenu la destination : il attend les
+    // octets, qu'il écrira lui-même. Écrire ici viserait le mauvais disque.
+    if (target.destination_relay) {
+        return [
+            {
+                type: "resource",
+                resource: {
+                    uri: `file:///${name}`,
+                    name,
+                    mimeType,
+                    blob: data.toString("base64"),
+                },
+            },
+        ];
+    }
+    // Pas de relais : le MCP tourne à côté de l'agent, son disque est le bon.
+    if (!path.isAbsolute(target.destination_path)) {
+        throw new Error(`destination_path must be an absolute directory path: ${target.destination_path}`);
+    }
+    if (fs.existsSync(target.destination_path) &&
+        !fs.statSync(target.destination_path).isDirectory()) {
+        throw new Error(`destination_path must be a directory, but a file already exists there: ${target.destination_path}`);
+    }
+    const written = path.join(target.destination_path, name);
+    if (!target.destination_overwrite && fs.existsSync(written)) {
+        throw new Error(`Destination already exists: ${written}. Pass destination_overwrite to replace it.`);
+    }
+    fs.mkdirSync(target.destination_path, { recursive: true });
+    fs.writeFileSync(written, data);
+    return [{ type: "text", text: `File written to ${written} (${data.length} bytes).` }];
+}

package/dist/src/tools/screenshot-design.js

@@ -1,6 +1,5 @@
-import fs from "fs";
-import path from "path";
 import { screenshotDesign } from "../core/screenshot.js";
+import { deliverFile } from "./relay.js";
 import { requireString } from "./types.js";
 /** Marge par défaut autour d'un noeud capturé : de l'air, sans noyer l'élément. */
 const NODE_PADDING = 16;
@@ -20,12 +19,19 @@ export function screenshotDesignTool(store, args) {
     const subject = node ? `${node.type} "${node.name}" (${node.id})` : `design "${design.name}"`;
     const geometry = `${Math.round(shot.sourceWidth)}x${Math.round(shot.sourceHeight)} design px ` +
         `rendered at ${shot.width}x${shot.height} px (scale ${Math.round(shot.scale * 100) / 100})`;
-    const outputPath = typeof args?.output_path === "string" ? args.output_path.trim() : "";
-    if (outputPath) {
-        const target = path.resolve(outputPath);
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.writeFileSync(target, shot.png);
-        return { content: [{ type: "text", text: `Screenshot of ${subject} written to ${target} — ${geometry}.` }] };
+    const destination = typeof args?.destination_path === "string" ? args.destination_path.trim() : "";
+    if (destination) {
+        // Livrer le PNG et le montrer à la fois n'aurait pas de sens : le relais retire le
+        // contenu du résultat, et une image de plus dans le contexte coûte cher pour rien.
+        const blocks = deliverFile(shot.png, "image/png", {
+            destination_path: destination,
+            filename: requireString(args, "filename"),
+            destination_overwrite: args?.destination_overwrite === true,
+            destination_relay: args?.destination_relay === true,
+        });
+        return {
+            content: [{ type: "text", text: `Screenshot of ${subject} — ${geometry}.` }, ...blocks],
+        };
     }
     return {
         content: [

package/dist/src/tools/types.d.ts

@@ -20,6 +20,25 @@ export interface ImageToolResult {
         type: "image";
         data: string;
         mimeType: string;
-    }>;
+    } | ResourceBlock>;
+    isError?: boolean;
+}
+/** Bloc qu'un outil renvoie pour un fichier que le relais du gateway écrira chez l'agent. */
+export interface ResourceBlock {
+    type: "resource";
+    resource: {
+        uri: string;
+        name: string;
+        mimeType: string;
+        blob: string;
+    };
+}
+/** Variante de ToolResult pour les outils qui peuvent livrer un fichier. */
+export interface FileToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    } | ResourceBlock>;
     isError?: boolean;
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.7";
+export declare const APP_VERSION = "1.0.8";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.7';
+export const APP_VERSION = '1.0.8';