@imenam/mcp-design 1.0.6 → 1.0.8

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);
@@ -41,8 +42,14 @@ const __dirname = path.dirname(__filename);
 // Les flags CLI sont traités avant toute initialisation : ils s'exécutent dans le
 // répertoire de l'utilisateur, pas dans un serveur MCP.
 if (process.argv.slice(2).includes("--claude-setup-mcp")) {
-    const { runSetupMcp } = await import("./cli/setup-mcp.js");
-    process.exit(runSetupMcp({ cwd: process.cwd(), force: process.argv.slice(2).includes("--force") }));
+    const argv = process.argv.slice(2);
+    const { runSetupMcp, parseGuiExposure } = await import("./cli/setup-mcp.js");
+    const parsed = parseGuiExposure(argv);
+    if ("error" in parsed) {
+        console.error(`Erreur : ${parsed.error}`);
+        process.exit(1);
+    }
+    process.exit(runSetupMcp({ cwd: process.cwd(), force: argv.includes("--force"), exposure: parsed.exposure }));
 }
 function findProjectRoot(startDir) {
     let current = startDir;
@@ -62,7 +69,7 @@ const logger = createLogger("mcp-design");
 function getConfig() {
     if (fs.existsSync(packageEnvPath))
         dotenv.config({ path: packageEnvPath, override: true });
-    return { proxyUrl: process.env.PROXY_URL, version: APP_VERSION };
+    return { proxyUrl: process.env.PROXY_URL, appPort: process.env.APP_PORT, version: APP_VERSION };
 }
 getConfig();
 const store = new DesignStore(rootDir);
@@ -224,9 +231,13 @@ guiLauncher = new GuiLauncher({
     maxRestarts: 0,
     onMessage: handleIPCMessage,
 });
+/** La GUI a besoin soit d'un proxy, soit d'un port local (mode standalone). */
+function guiIsConfigured() {
+    return !!(process.env.PROXY_URL?.trim() || process.env.APP_PORT?.trim());
+}
 function launchGUI() {
-    if (!process.env.PROXY_URL) {
-        logger.info("[MASTER] PROXY_URL non défini — GUI désactivée.");
+    if (!guiIsConfigured()) {
+        logger.info("[MASTER] Ni PROXY_URL ni APP_PORT défini — GUI désactivée.");
         guiStatus = "disabled";
         return;
     }
@@ -234,13 +245,13 @@ function launchGUI() {
     startGuiWorker();
 }
 async function reconnectGui(args) {
-    getConfig(); // relit le .env au cas où PROXY_URL aurait été ajouté après le démarrage
-    if (!process.env.PROXY_URL) {
+    getConfig(); // relit le .env au cas où PROXY_URL/APP_PORT aurait été ajouté après le démarrage
+    if (!guiIsConfigured()) {
         return {
             content: [
                 {
                     type: "text",
-                    text: "Error: PROXY_URL is not set — the GUI is disabled. Add PROXY_URL to the .env file, then call reconnect_gui again.",
+                    text: "Error: neither PROXY_URL nor APP_PORT is set — the GUI is disabled. Add PROXY_URL (to expose the GUI through the proxy) or APP_PORT (to serve it directly on localhost) to the .env file, then call reconnect_gui again.",
                 },
             ],
             isError: true,
@@ -253,13 +264,13 @@ async function reconnectGui(args) {
         if (guiStatus === "starting") {
             return {
                 content: [
-                    { type: "text", text: "GUI worker is already starting (proxy registration in progress). Wait a few seconds, then call reconnect_gui again if needed." },
+                    { type: "text", text: "GUI worker is already starting. Wait a few seconds, then call reconnect_gui again if needed." },
                 ],
             };
         }
         return {
             content: [
-                { type: "text", text: `GUI is already registered with the proxy${guiUrl ? ` at ${guiUrl}` : ""}. Nothing to do (use force=true to restart it anyway).` },
+                { type: "text", text: `GUI is already running${guiUrl ? ` at ${guiUrl}` : ""}. Nothing to do (use force=true to restart it anyway).` },
             ],
         };
     }
@@ -285,23 +296,25 @@ async function reconnectGui(args) {
         };
         newChild.on("exit", onExit);
     });
+    const proxyUrl = process.env.PROXY_URL?.trim();
     if (result.outcome === "ready") {
-        return { content: [{ type: "text", text: `GUI reconnected and registered with the proxy. URL: ${result.url}` }] };
+        return { content: [{ type: "text", text: `GUI reconnected. URL: ${result.url}` }] };
     }
     if (result.outcome === "already_running") {
-        return { content: [{ type: "text", text: `GUI is already registered by another MCP instance. URL: ${result.url ?? "unknown"}` }] };
+        return { content: [{ type: "text", text: `GUI is already served by another MCP instance. URL: ${result.url ?? "unknown"}` }] };
     }
     if (result.outcome === "exited") {
+        const hint = proxyUrl
+            ? `The proxy server is probably still unreachable at ${proxyUrl}. Start the proxy server, then call reconnect_gui again.`
+            : `Port ${process.env.APP_PORT} is probably already taken by another process. Free it or set another APP_PORT, then call reconnect_gui again.`;
         return {
-            content: [
-                { type: "text", text: `GUI worker exited before completing registration (code=${result.code}). The proxy server is probably still unreachable at ${process.env.PROXY_URL}. Start the proxy server, then call reconnect_gui again.` },
-            ],
+            content: [{ type: "text", text: `GUI worker exited before it was ready (code=${result.code}). ${hint}` }],
             isError: true,
         };
     }
     return {
         content: [
-            { type: "text", text: `GUI worker started but did not confirm proxy registration within 15s. Check the logs (${resolveLogDir(rootDir)}), then retry.` },
+            { type: "text", text: `GUI worker started but did not confirm it was ready within 15s. Check the logs (${resolveLogDir(rootDir)}), then retry.` },
         ],
         isError: true,
     };
@@ -323,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.";
@@ -676,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"],
             },
@@ -691,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: {
@@ -708,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.6";
+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.6';
+export const APP_VERSION = '1.0.8';