@imenam/mcp-gui-interface 1.0.3

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

@@ -0,0 +1,19 @@
+import { ChildProcess } from "child_process";
+import { IpcHub } from "./ipc-hub.js";
+import type { GuiLauncherOptions, IpcMessage } from "./types.js";
+export type { GuiLauncherOptions };
+export declare class GuiLauncher {
+    private readonly options;
+    private guiProcess;
+    private ipcHub;
+    private restartCount;
+    private readonly maxRestarts;
+    private readonly restartDelay;
+    constructor(options: GuiLauncherOptions);
+    private registerSignalHandlers;
+    start(): ChildProcess;
+    getProcess(): ChildProcess | null;
+    getIpcHub(): IpcHub;
+    send(message: Omit<IpcMessage, "timestamp">): boolean;
+    cleanup(): Promise<void>;
+}

package/dist/src/gui-launcher.js

@@ -0,0 +1,104 @@
+import { fork } from "child_process";
+import { createLogger } from "./logger.js";
+import { IpcHub } from "./ipc-hub.js";
+const logger = createLogger("GuiLauncher");
+export class GuiLauncher {
+    options;
+    guiProcess = null;
+    ipcHub = new IpcHub();
+    restartCount = 0;
+    maxRestarts;
+    restartDelay;
+    constructor(options) {
+        this.options = options;
+        this.maxRestarts = options.maxRestarts ?? 3;
+        this.restartDelay = options.restartDelay ?? 2000;
+        this.registerSignalHandlers();
+    }
+    registerSignalHandlers() {
+        const syncCleanup = () => {
+            this.guiProcess?.kill();
+            this.guiProcess = null;
+        };
+        process.on("exit", syncCleanup);
+        process.on("SIGINT", async () => {
+            await this.cleanup();
+            process.exit(0);
+        });
+        process.on("SIGTERM", async () => {
+            await this.cleanup();
+            process.exit(0);
+        });
+        process.stdin.on("close", async () => {
+            logger.info("stdin closed, shutting down.");
+            await this.cleanup();
+            process.exit(0);
+        });
+    }
+    start() {
+        if (this.guiProcess) {
+            this.guiProcess.kill();
+        }
+        logger.info(`Starting GUI process: ${this.options.guiPath}`);
+        this.guiProcess = fork(this.options.guiPath, [], {
+            stdio: ["ignore", "pipe", "inherit", "ipc"],
+            env: { ...process.env, ...this.options.env },
+        });
+        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.guiProcess.on("exit", (code, signal) => {
+            logger.info(`GUI process exited (code=${code}, signal=${signal})`);
+            // Only auto-restart on unexpected crashes (code !== 0 and code !== null)
+            const shouldRestart = code !== 0 && code !== null;
+            if (shouldRestart && this.restartCount < this.maxRestarts) {
+                this.restartCount++;
+                logger.warn(`Restarting GUI (attempt ${this.restartCount}/${this.maxRestarts}) in ${this.restartDelay}ms...`);
+                setTimeout(() => this.start(), this.restartDelay);
+            }
+            else if (shouldRestart) {
+                logger.error(`GUI crashed ${this.maxRestarts} times. Giving up.`);
+            }
+            else {
+                this.restartCount = 0;
+            }
+        });
+        this.guiProcess.on("error", (err) => {
+            logger.error(`GUI process error: ${err.message}`);
+        });
+        logger.info(`GUI process started (PID ${this.guiProcess.pid})`);
+        return this.guiProcess;
+    }
+    getProcess() {
+        return this.guiProcess;
+    }
+    getIpcHub() {
+        return this.ipcHub;
+    }
+    send(message) {
+        return this.ipcHub.send({ ...message, timestamp: new Date().toISOString() });
+    }
+    async cleanup() {
+        if (!this.guiProcess)
+            return;
+        logger.info("Cleaning up GUI process...");
+        const proc = this.guiProcess;
+        this.guiProcess = null;
+        await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                proc.kill("SIGKILL");
+                resolve();
+            }, 3000);
+            proc.once("exit", () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            proc.kill("SIGTERM");
+        });
+        logger.info("GUI process cleaned up.");
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { GuiLauncher, 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";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { GuiLauncher } 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/ipc-hub.d.ts

@@ -0,0 +1,11 @@
+import { ChildProcess } from "child_process";
+import type { IpcMessage } from "./types.js";
+export type { IpcMessage };
+export declare class IpcHub {
+    private targetProcess;
+    constructor(targetProcess?: ChildProcess);
+    setTargetProcess(targetProcess: ChildProcess): void;
+    send(message: IpcMessage): boolean;
+    onMessage(callback: (msg: IpcMessage) => void): void;
+    request(message: Omit<IpcMessage, "timestamp" | "correlationId">, timeout?: number): Promise<IpcMessage>;
+}

package/dist/src/ipc-hub.js

@@ -0,0 +1,65 @@
+import { createLogger } from "./logger.js";
+const logger = createLogger("IpcHub");
+export class IpcHub {
+    targetProcess = null;
+    constructor(targetProcess) {
+        if (targetProcess) {
+            this.targetProcess = targetProcess;
+        }
+    }
+    setTargetProcess(targetProcess) {
+        this.targetProcess = targetProcess;
+    }
+    send(message) {
+        if (this.targetProcess && this.targetProcess.connected) {
+            try {
+                return this.targetProcess.send(message) ?? false;
+            }
+            catch (err) {
+                logger.error(`Failed to send message: ${err.message}`);
+                return false;
+            }
+        }
+        return false;
+    }
+    onMessage(callback) {
+        if (this.targetProcess) {
+            this.targetProcess.on("message", (msg) => {
+                if (msg && typeof msg === "object" && "type" in msg) {
+                    callback(msg);
+                }
+            });
+        }
+    }
+    async request(message, timeout = 2000) {
+        if (!this.targetProcess || !this.targetProcess.connected) {
+            throw new Error("IPC target process not connected");
+        }
+        const correlationId = Math.random().toString(36).substring(7);
+        const fullMessage = {
+            ...message,
+            correlationId,
+            timestamp: new Date().toISOString(),
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.targetProcess?.off("message", handler);
+                reject(new Error(`IPC request timed out after ${timeout}ms`));
+            }, timeout);
+            const handler = (msg) => {
+                if (msg && msg.correlationId === correlationId) {
+                    clearTimeout(timer);
+                    this.targetProcess?.off("message", handler);
+                    resolve(msg);
+                }
+            };
+            this.targetProcess?.on("message", handler);
+            const sent = this.send(fullMessage);
+            if (!sent) {
+                clearTimeout(timer);
+                this.targetProcess?.off("message", handler);
+                reject(new Error("Failed to send IPC message"));
+            }
+        });
+    }
+}

package/dist/src/logger.d.ts

@@ -0,0 +1,3 @@
+import type { Logger, SetupLoggingOptions } from "./types.js";
+export declare function setupLogging(options: SetupLoggingOptions): void;
+export declare function createLogger(scope: string): Logger;

package/dist/src/logger.js

@@ -0,0 +1,69 @@
+import fs from "fs";
+import path from "path";
+import { inspect } from "util";
+let loggingInitialized = false;
+let currentProcessLabel = "PROCESS";
+let logStream = null;
+let consoleErrorPatched = false;
+let originalConsoleError = console.error;
+function serialize(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    return inspect(value, { depth: 5, breakLength: 120, compact: true });
+}
+function serializeArgs(args) {
+    return args.map((arg) => serialize(arg)).join(" ");
+}
+function writeToFile(message) {
+    if (!logStream)
+        return;
+    const entry = `[${new Date().toISOString()}] [PID ${process.pid}] [${currentProcessLabel}] ${message}\n`;
+    logStream.write(entry);
+}
+function ensureConsoleErrorPatched() {
+    if (consoleErrorPatched)
+        return;
+    originalConsoleError = console.error.bind(console);
+    console.error = (...args) => {
+        writeToFile(serializeArgs(args));
+        originalConsoleError(...args);
+    };
+    consoleErrorPatched = true;
+}
+function normalizeMessage(message, meta) {
+    if (meta.length === 0)
+        return message;
+    return `${message} ${serializeArgs(meta)}`;
+}
+export function setupLogging(options) {
+    if (loggingInitialized)
+        return;
+    currentProcessLabel = options.processLabel;
+    const resolvedLogDir = options.logDir ?? path.join(process.cwd(), ".mcp-gui", "logs");
+    fs.mkdirSync(resolvedLogDir, { recursive: true });
+    const logFilePath = path.join(resolvedLogDir, "server.log");
+    logStream = fs.createWriteStream(logFilePath, { flags: "a", encoding: "utf8" });
+    logStream.on("error", (error) => {
+        originalConsoleError(`Critical: Failed to write to log file: ${serialize(error)}`);
+    });
+    ensureConsoleErrorPatched();
+    // Redirect console.log/info/warn to console.error to protect stdout
+    // which is reserved for the MCP JSON-RPC protocol in the MASTER process.
+    console.log = (...args) => console.error(...args);
+    console.info = (...args) => console.error(...args);
+    console.warn = (...args) => console.error(...args);
+    loggingInitialized = true;
+    writeToFile("[INFO] [LOGGER] Logging system initialized");
+}
+export function createLogger(scope) {
+    const logWithLevel = (level, message, ...meta) => {
+        console.error(`[${level}] [${scope}] ${normalizeMessage(message, meta)}`);
+    };
+    return {
+        debug: (message, ...meta) => logWithLevel("DEBUG", message, ...meta),
+        info: (message, ...meta) => logWithLevel("INFO", message, ...meta),
+        warn: (message, ...meta) => logWithLevel("WARN", message, ...meta),
+        error: (message, ...meta) => logWithLevel("ERROR", message, ...meta),
+    };
+}

package/dist/src/proxy-client.d.ts

@@ -0,0 +1,11 @@
+import type { RegisterOptions, RegisterResult } from "./types.js";
+export type { RegisterOptions, RegisterResult };
+export declare class ProxyClient {
+    private proxyUrl;
+    private registeredPath?;
+    private status;
+    constructor(proxyUrl: string);
+    getStatus(): "connected" | "fallback" | "error";
+    register(options: RegisterOptions, fallbackPort: number): Promise<RegisterResult>;
+    unregister(): Promise<boolean>;
+}

package/dist/src/proxy-client.js

@@ -0,0 +1,114 @@
+import http from "http";
+import { createLogger } from "./logger.js";
+const logger = createLogger("ProxyClient");
+export class ProxyClient {
+    proxyUrl;
+    registeredPath;
+    status = "error";
+    constructor(proxyUrl) {
+        this.proxyUrl = proxyUrl;
+    }
+    getStatus() {
+        return this.status;
+    }
+    async register(options, fallbackPort) {
+        this.registeredPath = options.path;
+        return new Promise((resolve) => {
+            let url;
+            try {
+                url = new URL(`${this.proxyUrl}/proxy/register`.replace(/\/+/g, "/").replace(":/", "://"));
+            }
+            catch {
+                logger.error(`Invalid Proxy URL: ${this.proxyUrl}`);
+                this.status = "error";
+                return resolve({ success: false, port: fallbackPort, error: "Invalid Proxy URL" });
+            }
+            const timeout = 1000;
+            logger.info(`Sending registration request to ${url.href}...`);
+            const req = http.request({
+                hostname: url.hostname,
+                port: url.port || (url.protocol === "https:" ? 443 : 80),
+                path: url.pathname,
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                timeout,
+            }, (res) => {
+                logger.info(`Received response: HTTP ${res.statusCode}`);
+                let data = "";
+                res.on("data", (chunk) => (data += chunk));
+                res.on("end", () => {
+                    if (res.statusCode === 200 || res.statusCode === 201) {
+                        try {
+                            const raw = JSON.parse(data);
+                            if (raw &&
+                                typeof raw === "object" &&
+                                typeof raw.port === "number") {
+                                logger.info(`Registration verified. Allocated port: ${raw.port}`);
+                                this.status = "connected";
+                                resolve({ success: true, port: raw.port, url: raw.url });
+                            }
+                            else {
+                                logger.error(`Invalid proxy response schema: ${data}`);
+                                this.status = "fallback";
+                                resolve({ success: false, port: fallbackPort, error: "Invalid proxy response schema" });
+                            }
+                        }
+                        catch {
+                            logger.error(`JSON parse error: ${data}`);
+                            this.status = "fallback";
+                            resolve({ success: false, port: fallbackPort, error: "Invalid JSON response" });
+                        }
+                    }
+                    else {
+                        logger.error(`Registration rejected with HTTP ${res.statusCode}`);
+                        this.status = "fallback";
+                        resolve({ success: false, port: fallbackPort, error: `HTTP ${res.statusCode}` });
+                    }
+                });
+            });
+            req.on("error", (err) => {
+                logger.error(`Registration error: ${err.message}`);
+                this.status = "fallback";
+                resolve({ success: false, port: fallbackPort, error: err.message });
+            });
+            req.on("timeout", () => {
+                logger.error(`Registration timeout after ${timeout}ms`);
+                req.destroy();
+                this.status = "fallback";
+                resolve({ success: false, port: fallbackPort, error: "Timeout" });
+            });
+            req.write(JSON.stringify(options));
+            req.end();
+        });
+    }
+    async unregister() {
+        if (!this.registeredPath)
+            return true;
+        return new Promise((resolve) => {
+            let url;
+            try {
+                url = new URL(`${this.proxyUrl}/proxy/unregister`.replace(/\/+/g, "/").replace(":/", "://"));
+            }
+            catch {
+                return resolve(false);
+            }
+            const req = http.request({
+                hostname: url.hostname,
+                port: url.port || (url.protocol === "https:" ? 443 : 80),
+                path: url.pathname,
+                method: "DELETE",
+                headers: { "Content-Type": "application/json" },
+                timeout: 2000,
+            }, (res) => {
+                logger.info(`Unregister response: HTTP ${res.statusCode}`);
+                resolve(res.statusCode === 200);
+            });
+            req.on("error", (err) => {
+                logger.error(`Unregister error: ${err.message}`);
+                resolve(false);
+            });
+            req.write(JSON.stringify({ path: this.registeredPath }));
+            req.end();
+        });
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,41 @@
+export interface IpcMessage {
+    type: string;
+    correlationId?: string;
+    data?: any;
+    error?: string;
+    timestamp: string;
+}
+export interface ProxyConfig {
+    proxyUrl?: string;
+    appPath: string;
+    appName: string;
+    fallbackPort: number;
+}
+export interface RegisterResult {
+    success: boolean;
+    port: number;
+    url?: string;
+    error?: string;
+}
+export interface RegisterOptions {
+    path: string;
+    name?: string;
+    port?: number;
+}
+export interface Logger {
+    debug: (message: string, ...meta: unknown[]) => void;
+    info: (message: string, ...meta: unknown[]) => void;
+    warn: (message: string, ...meta: unknown[]) => void;
+    error: (message: string, ...meta: unknown[]) => void;
+}
+export interface SetupLoggingOptions {
+    processLabel: string;
+    logDir?: string;
+}
+export interface GuiLauncherOptions {
+    guiPath: string;
+    env?: Record<string, string>;
+    maxRestarts?: number;
+    restartDelay?: number;
+    onMessage?: (msg: IpcMessage) => void;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@imenam/mcp-gui-interface",
+  "version": "1.0.3",
+  "description": "Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "release": "npm version patch && npm run build && npm publish --access public && git push origin master --follow-tags"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gui",
+    "ipc",
+    "lifecycle",
+    "proxy",
+    "ai",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Matthieu-Pesnot-Pin/mcp-gui-interface.git"
+  },
+  "author": "Matthieu Pesnot-Pin",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "typescript": "^5.9.3"
+  }
+}