@imenam/mcp-gui-interface 1.0.8 → 1.0.11

package/README.md

@@ -174,6 +174,21 @@ await proxy.unregister();
 - Registration HTTP timeout: **1000 ms** (unregister: **2000 ms**).
 - On failure, `RegisterResult.port` is **`0`** in the current implementation.
 
+**Grouping (`group` / `APP_GROUP`):** pass an optional `group` in the register
+options to place the app under a collapsible section (folded by default) in the
+proxy dashboard. Apps sharing the same `group` are shown together; apps without
+one land in a default "ungrouped" section. When `group` is omitted, `register`
+falls back to the **`APP_GROUP`** environment variable, so an MCP can enable
+grouping purely from its `.env` without touching code:
+
+```typescript
+// Explicit:
+await proxy.register({ path: "/my-app", name: "My App", group: "Google" });
+
+// Or, with APP_GROUP=Google in the environment, simply:
+await proxy.register({ path: "/my-app", name: "My App" });
+```
+
 > **Older npm versions** may have exposed `register(options, fallbackPort)`. Check `node_modules/@imenam/mcp-gui-interface/dist/src/proxy-client.d.ts` for the exact signature you have installed.
 
 **`getStatus()`:** `"connected" | "fallback" | "error"` — many failure paths set `"error"`.

package/dist/src/gui-launcher.d.ts

@@ -1,6 +1,6 @@
 import { ChildProcess } from "child_process";
 import { IpcHub } from "./ipc-hub.js";
-import type { GuiLauncherOptions, IpcMessage } from "./types.js";
+import type { GuiLauncherOptions, GuiRuntimeStatus, IpcMessage, McpToolResult, ReconnectResult } from "./types.js";
 export type { GuiLauncherOptions };
 export declare class GuiLauncher {
     private readonly options;
@@ -9,11 +9,58 @@ export declare class GuiLauncher {
     private restartCount;
     private readonly maxRestarts;
     private readonly restartDelay;
+    private status;
+    private url;
+    private startWaiter;
     constructor(options: GuiLauncherOptions);
+    /** Current lifecycle state of the GUI worker. */
+    getStatus(): GuiRuntimeStatus;
+    /** URL the GUI is registered under, once known. */
+    getUrl(): string | null;
+    /**
+     * Intercepts the GUI worker's lifecycle messages to keep local state in sync,
+     * then forwards every message to the consumer's onMessage handler unchanged.
+     */
+    private handleMessage;
     private registerSignalHandlers;
     start(): ChildProcess;
     getProcess(): ChildProcess | null;
     getIpcHub(): IpcHub;
     send(message: Omit<IpcMessage, "timestamp">): boolean;
+    /**
+     * Relaunch the GUI worker and wait for it to re-register with the proxy.
+     * Safe to call when the proxy was down at MCP startup: it re-reads PROXY_URL
+     * (via the reloadEnv hook), relaunches the worker and resolves once the worker
+     * confirms READY / ALREADY_RUNNING, exits, or the timeout elapses.
+     */
+    reconnect(options?: {
+        force?: boolean;
+        timeoutMs?: number;
+    }): Promise<ReconnectResult>;
+    /**
+     * Runs reconnect() and adapts the result to the MCP tool-call return shape,
+     * so a server can wire the `reconnect_gui` tool in a single line:
+     *   case "reconnect_gui": return launcher.handleReconnectTool(args);
+     */
+    handleReconnectTool(args?: {
+        force?: boolean;
+    }): Promise<McpToolResult>;
     cleanup(): Promise<void>;
 }
+/**
+ * Ready-made MCP tool definition for `reconnect_gui`. Spread it into your
+ * server's tools list, then dispatch to `launcher.handleReconnectTool(args)`.
+ */
+export declare function reconnectGuiToolDefinition(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            force: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};

package/dist/src/gui-launcher.js

@@ -2,6 +2,7 @@ import { fork } from "child_process";
 import { createLogger } from "./logger.js";
 import { IpcHub } from "./ipc-hub.js";
 const logger = createLogger("GuiLauncher");
+const RECONNECT_TIMEOUT_MS = 15000;
 export class GuiLauncher {
     options;
     guiProcess = null;
@@ -9,12 +10,40 @@ export class GuiLauncher {
     restartCount = 0;
     maxRestarts;
     restartDelay;
+    status = "disabled";
+    url = null;
+    startWaiter = null;
     constructor(options) {
         this.options = options;
         this.maxRestarts = options.maxRestarts ?? 0;
         this.restartDelay = options.restartDelay ?? 2000;
         this.registerSignalHandlers();
     }
+    /** Current lifecycle state of the GUI worker. */
+    getStatus() {
+        return this.status;
+    }
+    /** URL the GUI is registered under, once known. */
+    getUrl() {
+        return this.url;
+    }
+    /**
+     * Intercepts the GUI worker's lifecycle messages to keep local state in sync,
+     * then forwards every message to the consumer's onMessage handler unchanged.
+     */
+    handleMessage(msg) {
+        if (msg.type === "ALREADY_RUNNING") {
+            this.status = "already_running";
+            this.url = msg.data?.url ?? this.url;
+            this.startWaiter?.({ outcome: "already_running", url: msg.data?.url });
+        }
+        else if (msg.type === "READY") {
+            this.status = "ready";
+            this.url = msg.data?.url ?? null;
+            this.startWaiter?.({ outcome: "ready", url: msg.data?.url });
+        }
+        this.options.onMessage?.(msg);
+    }
     registerSignalHandlers() {
         const syncCleanup = () => {
             this.guiProcess?.kill();
@@ -40,19 +69,25 @@ export class GuiLauncher {
             this.guiProcess.kill();
         }
         logger.info(`Starting GUI process: ${this.options.guiPath}`);
+        this.status = "starting";
         this.guiProcess = fork(this.options.guiPath, [], {
             stdio: ["ignore", "pipe", "inherit", "ipc"],
             env: { ...process.env, ...this.options.env },
         });
+        const child = this.guiProcess;
         this.guiProcess.stdout?.on("data", (data) => {
             process.stderr.write(data);
         });
         this.ipcHub = new IpcHub(this.guiProcess);
-        if (this.options.onMessage) {
-            this.ipcHub.onMessage(this.options.onMessage);
-        }
+        this.ipcHub.onMessage((msg) => this.handleMessage(msg));
         this.guiProcess.on("exit", (code, signal) => {
             logger.info(`GUI process exited (code=${code}, signal=${signal})`);
+            // A later start() replaces the current process: only the active process
+            // exiting should flip state to "stopped". ALREADY_RUNNING means the GUI
+            // lives in another instance, so this worker's exit is expected.
+            if (this.guiProcess === child && this.status !== "already_running") {
+                this.status = "stopped";
+            }
             // Only auto-restart on unexpected crashes (code !== 0 and code !== null)
             const shouldRestart = code !== 0 && code !== null;
             if (shouldRestart && this.restartCount < this.maxRestarts) {
@@ -82,6 +117,90 @@ export class GuiLauncher {
     send(message) {
         return this.ipcHub.send({ ...message, timestamp: new Date().toISOString() });
     }
+    /**
+     * Relaunch the GUI worker and wait for it to re-register with the proxy.
+     * Safe to call when the proxy was down at MCP startup: it re-reads PROXY_URL
+     * (via the reloadEnv hook), relaunches the worker and resolves once the worker
+     * confirms READY / ALREADY_RUNNING, exits, or the timeout elapses.
+     */
+    async reconnect(options) {
+        this.options.reloadEnv?.();
+        const proxyUrl = process.env.PROXY_URL;
+        if (!proxyUrl) {
+            this.status = "disabled";
+            return {
+                outcome: "disabled",
+                message: "PROXY_URL is not set — the GUI is disabled. Add PROXY_URL to the .env file, then call reconnect_gui again.",
+            };
+        }
+        const child = this.guiProcess;
+        const alive = !!child && child.exitCode === null && !child.killed;
+        const force = options?.force === true;
+        if (alive && !force) {
+            if (this.status === "starting") {
+                return {
+                    outcome: "noop",
+                    message: "GUI worker is already starting (proxy registration in progress). Wait a few seconds, then call reconnect_gui again if needed.",
+                };
+            }
+            return {
+                outcome: this.status === "already_running" ? "already_running" : "ready",
+                url: this.url ?? undefined,
+                message: `GUI is already registered with the proxy${this.url ? ` at ${this.url}` : ""}. Nothing to do (use force=true to restart it anyway).`,
+            };
+        }
+        logger.info(`reconnect: ${alive ? "restarting (force)" : "relaunching"} GUI worker...`);
+        const timeoutMs = options?.timeoutMs ?? RECONNECT_TIMEOUT_MS;
+        return await new Promise((resolve) => {
+            const newChild = this.start();
+            const cleanup = () => {
+                clearTimeout(timer);
+                newChild.off("exit", onExit);
+                this.startWaiter = null;
+            };
+            const onExit = (code) => {
+                cleanup();
+                resolve({
+                    outcome: "exited",
+                    code,
+                    message: `GUI worker exited before completing registration (code=${code}). The proxy server is probably still unreachable at ${proxyUrl}. Start the proxy server, then call reconnect_gui again.`,
+                });
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve({
+                    outcome: "timeout",
+                    message: `GUI worker started but did not confirm proxy registration within ${Math.round(timeoutMs / 1000)}s. Check the logs, then retry.`,
+                });
+            }, timeoutMs);
+            this.startWaiter = (r) => {
+                cleanup();
+                resolve({
+                    outcome: r.outcome,
+                    url: r.url,
+                    message: r.outcome === "ready"
+                        ? `GUI reconnected and registered with the proxy. URL: ${r.url}`
+                        : `GUI is already registered by another MCP instance. URL: ${r.url ?? "unknown"}`,
+                });
+            };
+            newChild.on("exit", onExit);
+        });
+    }
+    /**
+     * Runs reconnect() and adapts the result to the MCP tool-call return shape,
+     * so a server can wire the `reconnect_gui` tool in a single line:
+     *   case "reconnect_gui": return launcher.handleReconnectTool(args);
+     */
+    async handleReconnectTool(args) {
+        const result = await this.reconnect({ force: args?.force === true });
+        const isError = result.outcome === "disabled" ||
+            result.outcome === "exited" ||
+            result.outcome === "timeout";
+        return {
+            content: [{ type: "text", text: result.message }],
+            ...(isError ? { isError: true } : {}),
+        };
+    }
     async cleanup() {
         if (!this.guiProcess)
             return;
@@ -102,3 +221,22 @@ export class GuiLauncher {
         logger.info("GUI process cleaned up.");
     }
 }
+/**
+ * Ready-made MCP tool definition for `reconnect_gui`. Spread it into your
+ * server's tools list, then dispatch to `launcher.handleReconnectTool(args)`.
+ */
+export function reconnectGuiToolDefinition() {
+    return {
+        name: "reconnect_gui",
+        description: "Relaunch the GUI worker and re-register it with the proxy server. Use this when the proxy server was not running when the MCP server started (so the GUI registration failed), to redeploy the GUI without restarting the MCP server. Does nothing if the GUI is already registered, unless force=true.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                force: {
+                    type: "boolean",
+                    description: "Restart the GUI worker even if it is already running and registered (default: false)",
+                },
+            },
+        },
+    };
+}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
-export { GuiLauncher, type GuiLauncherOptions } from "./gui-launcher.js";
+export { GuiLauncher, reconnectGuiToolDefinition, type GuiLauncherOptions, } from "./gui-launcher.js";
 export { ProxyClient, type RegisterOptions, type RegisterResult } from "./proxy-client.js";
 export { IpcHub, type IpcMessage } from "./ipc-hub.js";
 export { setupLogging, createLogger } from "./logger.js";
-export type { ProxyConfig, Logger, SetupLoggingOptions } from "./types.js";
+export type { ProxyConfig, Logger, SetupLoggingOptions, GuiRuntimeStatus, ReconnectResult, McpToolResult, } from "./types.js";

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export { GuiLauncher } from "./gui-launcher.js";
+export { GuiLauncher, reconnectGuiToolDefinition, } from "./gui-launcher.js";
 export { ProxyClient } from "./proxy-client.js";
 export { IpcHub } from "./ipc-hub.js";
 export { setupLogging, createLogger } from "./logger.js";

package/dist/src/proxy-client.js

@@ -13,6 +13,14 @@ export class ProxyClient {
     }
     async register(options) {
         this.registeredPath = options.path;
+        // The group can be provided explicitly or, more conveniently, through the
+        // APP_GROUP env var — so any MCP using this library can opt into grouping
+        // from its .env alone. An empty/whitespace value means "ungrouped".
+        const rawGroup = options.group ?? process.env.APP_GROUP;
+        const group = typeof rawGroup === "string" && rawGroup.trim() !== ""
+            ? rawGroup.trim()
+            : undefined;
+        const payload = { ...options, ...(group ? { group } : {}) };
         return new Promise((resolve) => {
             let url;
             try {
@@ -77,7 +85,7 @@ export class ProxyClient {
                 this.status = "error";
                 resolve({ success: false, port: 0, error: "Timeout" });
             });
-            req.write(JSON.stringify(options));
+            req.write(JSON.stringify(payload));
             req.end();
         });
     }

package/dist/src/types.d.ts

@@ -21,6 +21,16 @@ export interface RegisterOptions {
     path: string;
     name?: string;
     port?: number;
+    /**
+     * Optional visual group. The proxy dashboard places every app sharing the
+     * same `group` under one collapsible section (folded by default). Apps left
+     * without a group land in a default "ungrouped" section.
+     *
+     * When omitted, {@link ProxyClient.register} falls back to the `APP_GROUP`
+     * environment variable, so an MCP can enable grouping purely from its `.env`
+     * without touching code.
+     */
+    group?: string;
 }
 export interface Logger {
     debug: (message: string, ...meta: unknown[]) => void;
@@ -38,4 +48,28 @@ export interface GuiLauncherOptions {
     maxRestarts?: number;
     restartDelay?: number;
     onMessage?: (msg: IpcMessage) => void;
+    /**
+     * Optional hook invoked at the start of reconnect() before PROXY_URL is read.
+     * Use it to reload the .env file (e.g. dotenv.config({ override: true }) or a
+     * custom getConfig()) so a PROXY_URL added after startup is picked up.
+     */
+    reloadEnv?: () => void;
+}
+/** Runtime lifecycle state of the GUI worker, tracked from its IPC messages. */
+export type GuiRuntimeStatus = "disabled" | "starting" | "ready" | "already_running" | "stopped";
+/** Structured outcome of a GuiLauncher.reconnect() call. */
+export interface ReconnectResult {
+    outcome: "ready" | "already_running" | "exited" | "timeout" | "disabled" | "noop";
+    url?: string;
+    code?: number | null;
+    /** Human-readable message suitable for returning to an MCP client. */
+    message: string;
+}
+/** MCP tool result shape (structural — avoids depending on the MCP SDK types). */
+export interface McpToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-gui-interface",
-  "version": "1.0.8",
+  "version": "1.0.11",
   "description": "Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging",
   "type": "module",
   "main": "./dist/src/index.js",