@imenam/mcp-gui-interface 1.0.13 → 1.0.15

package/README.md

@@ -1,369 +1,376 @@
-# @imenam/mcp-gui-interface
-
-Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging, and network exposure rules.
-
-This package encapsulates the boilerplate many MCP servers need when they run a companion GUI: spawning a child process safely, communicating over IPC, registering with the central HTTP proxy, and logging without polluting **stdout** (reserved for MCP JSON-RPC on the parent process).
-
----
-
-## Installation
-
-```bash
-npm install @imenam/mcp-gui-interface
-```
-
-No runtime dependencies. Requires Node.js with ESM support (`"type": "module"` in consuming packages).
-
----
-
-## Scope: Node only
-
-This package targets **Node.js processes** (MCP master and GUI worker). It is **not** meant for browser or Vite bundles — do not add it as a dependency of a React/Vite front-end.
-
----
-
-## How it fits together
-
-1. **MCP host** (e.g. Cursor) talks **only** to the **master** process over **stdio** (JSON-RPC). Nothing from this library runs in the host.
-2. The **master** may use **`GuiLauncher`** to **fork** a second Node process: the **GUI worker**. They talk over Node **IPC** (`process.send` / `message`).
-3. The **worker** starts an HTTP server (Express, Hono, …) and usually uses **`ProxyClient`** to register with your **HTTP proxy** so the UI gets a stable URL. It also serves the built SPA (static files).
-4. The **browser** loads that SPA. It talks to the worker via **HTTP** (`fetch`, SSE). It does **not** import this npm package—the worker is already a Node server.
-
-So: **two Node processes** (master + worker) may both depend on this package; the **browser bundle** must not.
-
-```mermaid
-flowchart LR
-  Host[MCP host]
-  Master[Master process]
-  Worker[GUI worker Node]
-  Proxy[HTTP proxy]
-  Browser[Browser]
-
-  Host <-->|stdio JSON-RPC| Master
-  Master -->|fork + IPC| Worker
-  Worker -->|register| Proxy
-  Browser -->|HTTP| Proxy
-  Proxy --> Worker
-```
-
-For a longer French walkthrough, see **MCP Documentor** → project **`mcp-gui-interface`** → *Guide d’utilisation — @imenam/mcp-gui-interface*.
-
----
-
-## Why this library exists
-
-MCP servers talk to the host (Cursor, Claude Desktop, etc.) over **stdout** using JSON-RPC. Any stray `console.log` on stdout can corrupt the protocol.
-
-When an MCP server also serves a GUI (Express, Hono, etc.), it typically must:
-
-1. **Fork** the GUI as a **separate child process** so the GUI’s stdout does not mix with the parent’s JSON-RPC channel.
-2. Exchange messages over **Node IPC** (`process.send` / `message`).
-3. **Register** the GUI with the central proxy ([mcp-http-gateway](https://github.com/Matthieu-Pesnot-Pin/mcp-http-gateway)) so it is reachable under a stable path.
-4. **Log safely** — stderr and/or a log file; never rely on stdout for logs in the master process.
-
-This library supports these patterns via `GuiLauncher`, `IpcHub`, `ProxyClient`, and `setupLogging` / `createLogger`.
-
----
-
-## API reference
-
-### `GuiLauncher`
-
-Spawns and supervises a GUI child process (`fork` with `stdio: ['ignore', 'pipe', 'inherit', 'ipc']` — child stdout is piped to the parent’s stderr).
-
-```typescript
-import { GuiLauncher } from "@imenam/mcp-gui-interface";
-
-const launcher = new GuiLauncher({
-  guiPath: "./dist/gui-worker.js",
-  env: { ...process.env } as Record<string, string>,
-  maxRestarts: 0, // default: 0 — no auto-restart unless you opt in
-  restartDelay: 2000, // default: 2000 ms between restart attempts
-  onMessage: (msg) => {
-    console.error("Received:", msg);
-  },
-});
-
-launcher.start();
-```
-
-**`GuiLauncherOptions`**
-
-| Property       | Type                         | Default | Description |
-|----------------|------------------------------|---------|-------------|
-| `guiPath`      | `string`                     | —       | Path to the GUI entry script (forked with Node) |
-| `env`          | `Record<string, string>`     | —       | Extra env vars merged with `process.env` |
-| `maxRestarts`  | `number`                     | **`0`** | Auto-restarts after unexpected exit (non-zero code) |
-| `restartDelay` | `number`                     | `2000`  | Ms to wait before each restart |
-| `onMessage`    | `(msg: IpcMessage) => void`  | —       | Incoming IPC from the child |
-
-**Methods**
-
-| Method           | Returns              | Description |
-|------------------|----------------------|-------------|
-| `start()`        | `ChildProcess`       | Spawns or respawns the GUI |
-| `send(message)`  | `boolean`            | Sends IPC to the child (timestamp added internally) |
-| `getIpcHub()`    | `IpcHub`             | Lower-level IPC helper |
-| `getProcess()`   | `ChildProcess \| null` | Current child, if any |
-| `cleanup()`      | `Promise<void>`      | SIGTERM, then SIGKILL after 3s if needed |
-
-The launcher registers handlers for `SIGINT`, `SIGTERM`, parent `exit`, and stdin `close` to tear down the child.
-
----
-
-### `IpcHub`
-
-Typed IPC between parent and child. Usually obtained via `launcher.getIpcHub()`.
-
-```typescript
-const ipc = launcher.getIpcHub();
-
-ipc.send({
-  type: "CONFIG_UPDATE",
-  data: { theme: "dark" },
-  timestamp: new Date().toISOString(),
-});
-
-const response = await ipc.request({ type: "GET_STATUS" }, 3000);
-```
-
-**`IpcMessage`**
-
-```typescript
-interface IpcMessage {
-  type: string;
-  correlationId?: string;
-  data?: any;
-  error?: string;
-  timestamp: string;
-}
-```
-
-**Methods**
-
-| Method                     | Description |
-|----------------------------|-------------|
-| `send(message)`            | Returns `false` if not connected |
-| `onMessage(callback)`      | Only delivers objects with a `type` field |
-| `request(message, timeout?)` | Default timeout **2000 ms** |
-
----
-
-### `ProxyClient`
-
-Registers / unregisters the GUI with the proxy (`POST /proxy/register`, `DELETE /proxy/unregister`).
-
-**Current API (source / recent releases):**
-
-```typescript
-import { ProxyClient } from "@imenam/mcp-gui-interface";
-
-const proxy = new ProxyClient(process.env.PROXY_URL!);
-
-const result = await proxy.register({ path: "/my-app", name: "My App" });
-
-if (result.success) {
-  console.error(`Listening on port ${result.port}`, result.url);
-} else {
-  console.error(result.error, result.port); // port is 0 on failure
-}
-
-await proxy.unregister();
-```
-
-- Registration HTTP timeout: **1000 ms** (unregister: **2000 ms**).
-- On failure, `RegisterResult.port` is **`0`** in the current implementation.
-
-#### Path & name resolution (`APP_PATH`, `APP_PATH_PREFIX`, …)
-
-`register({ path })` treats `path` as the MCP's **natural** path — the default
-hardcoded in its own source. The effective path is resolved from the
-environment, and comes back in `result.path`:
-
-| Variable | Role |
-|---|---|
-| `APP_PATH` | **Canonical.** Explicit mount path. Replaces the natural path. |
-| `PROXY_APP_PATH` | Fallback (Express MCPs), used when `APP_PATH` is unset. |
-| `GUI_PATH` | Fallback (gitHubMCP), used when the two above are unset. |
-| `APP_PATH_PREFIX` | Namespace prefixed to the **natural** path. |
-| `APP_NAME` / `PROXY_APP_NAME` / `GUI_NAME` | Display name, same priority order. |
-| `APP_GROUP` | Proxy dashboard group (empty value = ungrouped). |
-
-**The rule, exactly:**
-
-1. If any of `APP_PATH` → `PROXY_APP_PATH` → `GUI_PATH` is set to a non-empty
-   value, that value is the path, **taken as-is and never prefixed**.
-2. Otherwise the natural path is used, with `APP_PATH_PREFIX` prepended.
-3. Both are normalised: leading `/` added, `//` collapsed, trailing `/` removed.
-   An empty prefix, or `/`, has no effect.
-4. Prefixing is idempotent — a path already under the prefix is left alone, so
-   resolving twice is safe.
-
-**Why an explicit path is never prefixed.** `APP_PATH_PREFIX` exists for a
-supervisor that namespaces the GUIs it starts without knowing their natural
-paths. Someone who types `APP_PATH=/whatever` by hand is stating the *final*
-path and must get exactly that; the prefix only namespaces a value nobody
-chose. Setting `APP_PATH` is therefore also the way to opt out of prefixing.
-
-```typescript
-// APP_PATH_PREFIX=/abc123, no APP_PATH:
-const r = await proxy.register({ path: "/documentor-gui" });
-r.path; // "/abc123/documentor-gui"
-r.url;  // "http://localhost:3000/abc123/documentor-gui"
-```
-
-> **Always build the SPA's `<base href>` and any public URL from `result.path` /
-> `result.url`**, never from the path you passed in — otherwise assets are
-> requested one path segment too high and the page loads blank.
-
-The same resolution is exported standalone, for code that needs the path before
-registering:
-
-```typescript
-import { resolveAppPath, resolveAppName, resolveAppGroup } from "@imenam/mcp-gui-interface";
-
-const appPath = resolveAppPath("/documentor-gui"); // same rule, idempotent
-```
-
-**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"`.
-
----
-
-### `setupLogging` / `createLogger`
-
-Safe logging for MCP servers: protect stdout, mirror errors to a file.
-
-```typescript
-import { setupLogging, createLogger } from "@imenam/mcp-gui-interface";
-
-setupLogging({
-  processLabel: "MY-MCP",
-  logDir: "./logs", // optional; overrides MCP_LOG_DIR env var and .mcp-gui/logs default
-});
-
-const logger = createLogger("MyModule");
-logger.info("Server started");
-```
-
-**`setupLogging`**
-
-- Runs once per process (subsequent calls are no-ops).
-- Creates `logDir`, appends to **`server.log`** (single file — **no built-in rotation**).
-- Redirects `console.log` / `info` / `warn` → `console.error`.
-- Patches `console.error` to also append to the log file.
-
-**Log directory resolution order:**
-
-1. `logDir` option passed to `setupLogging`
-2. `MCP_LOG_DIR` environment variable
-3. `.mcp-gui/logs` relative to `process.cwd()` (default)
-
-**`createLogger(scope)`** — logs to stderr with `[LEVEL] [scope] …`.
-
----
-
-### Network exposure: `GUI_LISTEN_HOST` and the request guard
-
-A GUI worker must listen on the loopback interface only. Other machines reach it through the proxy or the gateway manager, which authenticate the user and relay to `localhost:<port>` / `127.0.0.1:<port>`.
-
-```typescript
-import { GUI_LISTEN_HOST, honoGuiGuard, expressGuiGuard } from "@imenam/mcp-gui-interface";
-
-// Hono
-app.use("*", honoGuiGuard());
-serve({ fetch: app.fetch, port, hostname: GUI_LISTEN_HOST });
-
-// Express — register the guard before any route or body parser
-app.use(expressGuiGuard());
-app.listen(port, GUI_LISTEN_HOST);
-```
-
-Never pass `"localhost"` as the listen host: depending on the system it resolves to `::1` or `127.0.0.1`. Never omit the host either: Node then listens on every interface.
-
-The guard refuses with a `403` JSON body `{ error }`:
-
-| Rule | Refused request | Protects against |
-|------|-----------------|------------------|
-| **Host** | a `Host` header other than `localhost`, `127.0.0.1` or `::1` | DNS rebinding: a hostile domain resolving to 127.0.0.1 |
-| **Cross-site modification** | a method other than GET/HEAD/OPTIONS with `Sec-Fetch-Site` other than `same-origin`/`none`; when that header is absent, an `Origin` whose hostname is neither this machine's (hostname, interface addresses, loopback), nor the proxy's, nor in `trustedOrigins` | CSRF: a web page submitting a form or a `fetch` to the GUI |
-
-Requests carrying neither `Sec-Fetch-Site` nor `Origin` (curl, scripts) pass the second rule. Reads are never refused on their origin: without CORS headers, the browser does not let another site read the responses. Do not add a CORS middleware to a GUI worker.
-
-**`GuiRequestGuardOptions`**
-
-| Property         | Type       | Default             | Description |
-|------------------|------------|---------------------|-------------|
-| `proxyUrl`       | `string`   | `process.env.PROXY_URL` | Its hostname is a trusted origin |
-| `trustedOrigins` | `string[]` | `[]`                | Other origins whose hostname is trusted, e.g. a gateway manager served over plain HTTP under a domain name |
-
-`checkGuiRequest(info, trustedOriginHostnames(options))` applies the same rules to any other server (for instance an `upgrade` handler).
-
----
-
-## Full-stack usage sketch
-
-Typical split:
-
-1. **Master:** `setupLogging`, optional `GuiLauncher` + `start()` when `PROXY_URL` (or your policy) allows.
-2. **GUI worker:** `setupLogging`, request guard, `ProxyClient.register`, bind HTTP server to returned port on `GUI_LISTEN_HOST`, `unregister` on shutdown.
-
-The master example in older docs that called `ProxyClient` in the same process as `GuiLauncher` is valid for simple layouts; **Hono-based** MCPs (e.g. MCP Documentor) often register the proxy **only** in the worker.
-
----
-
-## Exported types
-
-```typescript
-import type {
-  GuiLauncherOptions,
-  IpcMessage,
-  RegisterOptions,
-  RegisterResult,
-  ProxyConfig,
-  Logger,
-  SetupLoggingOptions,
-  GuiRequestGuardOptions,
-  GuiRequestInfo,
-  GuiRequestRejection,
-} from "@imenam/mcp-gui-interface";
-```
-
----
-
-## Development
-
-```bash
-npm run build        # tsc → dist/
-npm run build:watch
-npm test             # build, then node --test test/*.test.mjs
-npm run release      # version patch, build, publish, push tags
-```
-
----
-
-## Documentation interne
-
-Un **guide d’utilisation** (comment intégrer la lib dans un MCP + GUI) est maintenu dans **MCP Documentor**, projet **`mcp-gui-interface`**, entrée *Guide d’utilisation — @imenam/mcp-gui-interface* (dossier `guide`).
-
----
-
-## License
-
-ISC © [Matthieu Pesnot-Pin](https://github.com/Matthieu-Pesnot-Pin)
+# @imenam/mcp-gui-interface
+
+Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging, and network exposure rules.
+
+This package encapsulates the boilerplate many MCP servers need when they run a companion GUI: spawning a child process safely, communicating over IPC, registering with the central HTTP proxy, and logging without polluting **stdout** (reserved for MCP JSON-RPC on the parent process).
+
+---
+
+## Installation
+
+```bash
+npm install @imenam/mcp-gui-interface
+```
+
+No runtime dependencies. Requires Node.js with ESM support (`"type": "module"` in consuming packages).
+
+---
+
+## Scope: Node only
+
+This package targets **Node.js processes** (MCP master and GUI worker). It is **not** meant for browser or Vite bundles — do not add it as a dependency of a React/Vite front-end.
+
+---
+
+## How it fits together
+
+1. **MCP host** (e.g. Cursor) talks **only** to the **master** process over **stdio** (JSON-RPC). Nothing from this library runs in the host.
+2. The **master** may use **`GuiLauncher`** to **fork** a second Node process: the **GUI worker**. They talk over Node **IPC** (`process.send` / `message`).
+3. The **worker** starts an HTTP server (Express, Hono, …) and usually uses **`ProxyClient`** to register with your **HTTP proxy** so the UI gets a stable URL. It also serves the built SPA (static files).
+4. The **browser** loads that SPA. It talks to the worker via **HTTP** (`fetch`, SSE). It does **not** import this npm package—the worker is already a Node server.
+
+So: **two Node processes** (master + worker) may both depend on this package; the **browser bundle** must not.
+
+```mermaid
+flowchart LR
+  Host[MCP host]
+  Master[Master process]
+  Worker[GUI worker Node]
+  Proxy[HTTP proxy]
+  Browser[Browser]
+
+  Host <-->|stdio JSON-RPC| Master
+  Master -->|fork + IPC| Worker
+  Worker -->|register| Proxy
+  Browser -->|HTTP| Proxy
+  Proxy --> Worker
+```
+
+For a longer French walkthrough, see **MCP Documentor** → project **`mcp-gui-interface`** → *Guide d’utilisation — @imenam/mcp-gui-interface*.
+
+---
+
+## Why this library exists
+
+MCP servers talk to the host (Cursor, Claude Desktop, etc.) over **stdout** using JSON-RPC. Any stray `console.log` on stdout can corrupt the protocol.
+
+When an MCP server also serves a GUI (Express, Hono, etc.), it typically must:
+
+1. **Fork** the GUI as a **separate child process** so the GUI’s stdout does not mix with the parent’s JSON-RPC channel.
+2. Exchange messages over **Node IPC** (`process.send` / `message`).
+3. **Register** the GUI with the central proxy ([mcp-http-gateway](https://github.com/Matthieu-Pesnot-Pin/mcp-http-gateway)) so it is reachable under a stable path.
+4. **Log safely** — stderr and/or a log file; never rely on stdout for logs in the master process.
+
+This library supports these patterns via `GuiLauncher`, `IpcHub`, `ProxyClient`, and `setupLogging` / `createLogger`.
+
+---
+
+## API reference
+
+### `GuiLauncher`
+
+Spawns and supervises a GUI child process (`fork` with `stdio: ['ignore', 'pipe', 'inherit', 'ipc']` — child stdout is piped to the parent’s stderr).
+
+```typescript
+import { GuiLauncher } from "@imenam/mcp-gui-interface";
+
+const launcher = new GuiLauncher({
+  guiPath: "./dist/gui-worker.js",
+  env: { ...process.env } as Record<string, string>,
+  maxRestarts: 0, // default: 0 — no auto-restart unless you opt in
+  restartDelay: 2000, // default: 2000 ms between restart attempts
+  onMessage: (msg) => {
+    console.error("Received:", msg);
+  },
+});
+
+launcher.start();
+```
+
+**`GuiLauncherOptions`**
+
+| Property       | Type                         | Default | Description |
+|----------------|------------------------------|---------|-------------|
+| `guiPath`      | `string`                     | —       | Path to the GUI entry script (forked with Node) |
+| `env`          | `Record<string, string>`     | —       | Extra env vars merged with `process.env` |
+| `maxRestarts`  | `number`                     | **`0`** | Auto-restarts after unexpected exit (non-zero code) |
+| `restartDelay` | `number`                     | `2000`  | Ms to wait before each restart |
+| `onMessage`    | `(msg: IpcMessage) => void`  | —       | Incoming IPC from the child |
+
+**Methods**
+
+| Method           | Returns              | Description |
+|------------------|----------------------|-------------|
+| `start()`        | `ChildProcess`       | Spawns or respawns the GUI |
+| `send(message)`  | `boolean`            | Sends IPC to the child (timestamp added internally) |
+| `getIpcHub()`    | `IpcHub`             | Lower-level IPC helper |
+| `getProcess()`   | `ChildProcess \| null` | Current child, if any |
+| `cleanup()`      | `Promise<void>`      | SIGTERM, then SIGKILL after 3s if needed |
+
+The launcher registers handlers for `SIGINT`, `SIGTERM`, parent `exit`, and stdin `close` to tear down the child.
+
+---
+
+### `IpcHub`
+
+Typed IPC between parent and child. Usually obtained via `launcher.getIpcHub()`.
+
+```typescript
+const ipc = launcher.getIpcHub();
+
+ipc.send({
+  type: "CONFIG_UPDATE",
+  data: { theme: "dark" },
+  timestamp: new Date().toISOString(),
+});
+
+const response = await ipc.request({ type: "GET_STATUS" }, 3000);
+```
+
+**`IpcMessage`**
+
+```typescript
+interface IpcMessage {
+  type: string;
+  correlationId?: string;
+  data?: any;
+  error?: string;
+  timestamp: string;
+}
+```
+
+**Methods**
+
+| Method                     | Description |
+|----------------------------|-------------|
+| `send(message)`            | Returns `false` if not connected |
+| `onMessage(callback)`      | Only delivers objects with a `type` field |
+| `request(message, timeout?)` | Default timeout **2000 ms** |
+
+---
+
+### `ProxyClient`
+
+Registers / unregisters the GUI with the proxy (`POST /proxy/register`, `DELETE /proxy/unregister`).
+
+**Current API (source / recent releases):**
+
+```typescript
+import { ProxyClient } from "@imenam/mcp-gui-interface";
+
+const proxy = new ProxyClient(process.env.PROXY_URL!);
+
+const result = await proxy.register({ path: "/my-app", name: "My App" });
+
+if (result.success) {
+  console.error(`Listening on port ${result.port}`, result.url);
+} else {
+  console.error(result.error, result.port); // port is 0 on failure
+}
+
+await proxy.unregister();
+```
+
+- Registration HTTP timeout: **1000 ms** (unregister: **2000 ms**).
+- On failure, `RegisterResult.port` is **`0`** in the current implementation.
+
+#### Path & name resolution (`APP_PATH`, `APP_PATH_PREFIX`, …)
+
+`register({ path })` treats `path` as the MCP's **natural** path — the default
+hardcoded in its own source. The effective path is resolved from the
+environment, and comes back in `result.path`:
+
+| Variable | Role |
+|---|---|
+| `APP_PATH` | **Canonical.** Explicit mount path. Replaces the natural path. |
+| `PROXY_APP_PATH` | Fallback (Express MCPs), used when `APP_PATH` is unset. |
+| `GUI_PATH` | Fallback (gitHubMCP), used when the two above are unset. |
+| `APP_PATH_PREFIX` | Namespace prefixed to the **natural** path. |
+| `APP_NAME` / `PROXY_APP_NAME` / `GUI_NAME` | Display name, same priority order. |
+| `APP_GROUP` | Proxy dashboard group (empty value = ungrouped). |
+
+**The rule, exactly:**
+
+1. If any of `APP_PATH` → `PROXY_APP_PATH` → `GUI_PATH` is set to a non-empty
+   value, that value is the path, **taken as-is and never prefixed**.
+2. Otherwise the natural path is used, with `APP_PATH_PREFIX` prepended.
+3. Both are normalised: leading `/` added, `//` collapsed, trailing `/` removed.
+   An empty prefix, or `/`, has no effect.
+4. Prefixing is idempotent — a path already under the prefix is left alone, so
+   resolving twice is safe.
+
+**Why an explicit path is never prefixed.** `APP_PATH_PREFIX` exists for a
+supervisor that namespaces the GUIs it starts without knowing their natural
+paths. Someone who types `APP_PATH=/whatever` by hand is stating the *final*
+path and must get exactly that; the prefix only namespaces a value nobody
+chose. Setting `APP_PATH` is therefore also the way to opt out of prefixing.
+
+```typescript
+// APP_PATH_PREFIX=/abc123, no APP_PATH:
+const r = await proxy.register({ path: "/documentor-gui" });
+r.path; // "/abc123/documentor-gui"
+r.url;  // "http://localhost:3000/abc123/documentor-gui"
+```
+
+> **Always build the SPA's `<base href>` and any public URL from `result.path` /
+> `result.url`**, never from the path you passed in — otherwise assets are
+> requested one path segment too high and the page loads blank.
+
+The same resolution is exported standalone, for code that needs the path before
+registering:
+
+```typescript
+import { resolveAppPath, resolveAppName, resolveAppGroup } from "@imenam/mcp-gui-interface";
+
+const appPath = resolveAppPath("/documentor-gui"); // same rule, idempotent
+```
+
+**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"`.
+
+---
+
+### `setupLogging` / `createLogger`
+
+Safe logging for MCP servers: protect stdout, mirror errors to a file.
+
+```typescript
+import { setupLogging, createLogger } from "@imenam/mcp-gui-interface";
+
+setupLogging({
+  processLabel: "MY-MCP",
+  logDir: "./logs", // optional; overrides MCP_LOG_DIR env var and .mcp-gui/logs default
+});
+
+const logger = createLogger("MyModule");
+logger.info("Server started");
+```
+
+**`setupLogging`**
+
+- Runs once per process (subsequent calls are no-ops).
+- Creates `logDir`, appends to **`server.log`** (single file — **no built-in rotation**).
+- Redirects `console.log` / `info` / `warn` → `console.error`.
+- Patches `console.error` to also append to the log file.
+
+**Log directory resolution order:**
+
+1. `logDir` option passed to `setupLogging`
+2. `MCP_LOG_DIR` environment variable
+3. `.mcp-gui/logs` relative to `process.cwd()` (default)
+
+**`createLogger(scope)`** — logs to stderr with `[LEVEL] [scope] …`.
+
+---
+
+### Network exposure: `GUI_LISTEN_HOST` and the request guard
+
+A GUI worker must listen on the loopback interface only. Other machines reach it through the proxy or the gateway manager, which authenticate the user and relay to `localhost:<port>` / `127.0.0.1:<port>`.
+
+```typescript
+import { GUI_LISTEN_HOST, honoGuiGuard, expressGuiGuard } from "@imenam/mcp-gui-interface";
+
+// Hono
+app.use("*", honoGuiGuard());
+serve({ fetch: app.fetch, port, hostname: GUI_LISTEN_HOST });
+
+// Express — register the guard before any route or body parser
+app.use(expressGuiGuard());
+app.listen(port, GUI_LISTEN_HOST);
+```
+
+Never pass `"localhost"` as the listen host: depending on the system it resolves to `::1` or `127.0.0.1`. Never omit the host either: Node then listens on every interface.
+
+The guard refuses with a `403` JSON body `{ error }`:
+
+| Rule | Refused request | Protects against |
+|------|-----------------|------------------|
+| **Host** | a `Host` header other than `localhost`, `127.0.0.1` or `::1` | DNS rebinding: a hostile domain resolving to 127.0.0.1 |
+| **Cross-site modification** | a method other than GET/HEAD/OPTIONS with `Sec-Fetch-Site` other than `same-origin`/`none`; when that header is absent, an `Origin` whose hostname is neither this machine's (hostname, interface addresses, loopback), nor the proxy's, nor in `trustedOrigins` | CSRF: a web page submitting a form or a `fetch` to the GUI |
+
+When the network interfaces cannot be listed (a systemd sandbox with `RestrictAddressFamilies` lacking `AF_NETLINK`), the guard logs a warning and does not trust this machine's IP addresses as origins; list them in `trustedOrigins` if the GUI is opened through them over plain HTTP.
+
+Requests carrying neither `Sec-Fetch-Site` nor `Origin` (curl, scripts) pass the second rule. Reads are never refused on their origin: without CORS headers, the browser does not let another site read the responses. Do not add a CORS middleware to a GUI worker.
+
+**`GuiRequestGuardOptions`**
+
+| Property         | Type       | Default             | Description |
+|------------------|------------|---------------------|-------------|
+| `proxyUrl`       | `string`   | `process.env.PROXY_URL` | Its hostname is a trusted origin |
+| `trustedOrigins` | `string[]` | `[]`                | Other origins whose hostname is trusted, e.g. a gateway manager served over plain HTTP under a domain name |
+
+`checkGuiRequest(info, trustedOriginHostnames(options))` applies the same rules to any other server (for instance an `upgrade` handler).
+
+---
+
+## Full-stack usage sketch
+
+Typical split:
+
+1. **Master:** `setupLogging`, optional `GuiLauncher` + `start()` when `PROXY_URL` (or your policy) allows.
+2. **GUI worker:** `setupLogging`, request guard, `ProxyClient.register`, bind HTTP server to returned port on `GUI_LISTEN_HOST`, `unregister` on shutdown.
+
+The master example in older docs that called `ProxyClient` in the same process as `GuiLauncher` is valid for simple layouts; **Hono-based** MCPs (e.g. MCP Documentor) often register the proxy **only** in the worker.
+
+---
+
+## Exported types
+
+```typescript
+import type {
+  GuiLauncherOptions,
+  IpcMessage,
+  RegisterOptions,
+  RegisterResult,
+  ProxyConfig,
+  Logger,
+  SetupLoggingOptions,
+  GuiRequestGuardOptions,
+  GuiRequestInfo,
+  GuiRequestRejection,
+} from "@imenam/mcp-gui-interface";
+```
+
+---
+
+## Development
+
+```bash
+npm run build        # tsc → dist/
+npm run build:watch
+npm test             # build, then node --test test/*.test.mjs
+```
+
+---
+
+## Documentation interne
+
+Un **guide d’utilisation** (comment intégrer la lib dans un MCP + GUI) est maintenu dans **MCP Documentor**, projet **`mcp-gui-interface`**, entrée *Guide d’utilisation — @imenam/mcp-gui-interface* (dossier `guide`).
+
+---
+
+## Publication
+
+Chaque push sur `master`, merge de pull request compris, publie une nouvelle version de `@imenam/mcp-gui-interface` sur npm (`.github/workflows/publish.yml`) : `npm ci`, build et tests, puis `npm version patch`, dont le commit et le tag sont poussés sur `master`, et `npm publish`. La publication passe par le trusted publishing de npm (OIDC, sans token), avec attestation de provenance. Un échec du build ou des tests arrête le workflow avant la montée de version.
+
+Sur npmjs.com, le paquet déclare ce workflow comme publieur de confiance (Settings → Trusted publishing → GitHub Actions : `Matthieu-Pesnot-Pin`, `mcp-gui-interface`, `publish.yml`, avec `npm publish` dans les actions autorisées). Le commit de version est poussé avec `GITHUB_TOKEN` : si `master` est protégée, la règle doit autoriser GitHub Actions à y pousser.
+
+## License
+
+ISC © [Matthieu Pesnot-Pin](https://github.com/Matthieu-Pesnot-Pin)

package/dist/src/request-guard.js

@@ -20,6 +20,7 @@
  *    `trustedOrigins`. Requests without either header (curl, scripts) pass.
  */
 import os from "node:os";
+import { createLogger } from "./logger.js";
 /** Interface every GUI worker binds to. */
 export const GUI_LISTEN_HOST = "127.0.0.1";
 const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "::1"];
@@ -48,6 +49,25 @@ function originHostname(origin) {
         return null;
     }
 }
+const logger = createLogger("GuiRequestGuard");
+/**
+ * Addresses of this machine's network interfaces. A sandbox that forbids
+ * netlink sockets (systemd `RestrictAddressFamilies` without `AF_NETLINK`)
+ * makes the listing fail: the addresses are then not trusted, and a warning
+ * says so.
+ */
+function interfaceAddresses() {
+    let interfaces;
+    try {
+        interfaces = os.networkInterfaces();
+    }
+    catch (error) {
+        logger.warn(`Network interfaces cannot be listed (${error instanceof Error ? error.message : String(error)}): ` +
+            "origins using this machine's IP addresses are not trusted; list them in trustedOrigins if needed.");
+        return [];
+    }
+    return Object.values(interfaces).flatMap((addresses) => (addresses ?? []).map((address) => address.address.toLowerCase()));
+}
 /**
  * Hostnames an `Origin` may carry: loopback names, this machine's hostname and
  * interface addresses, the proxy's hostname and those of `trustedOrigins`.
@@ -55,10 +75,8 @@ function originHostname(origin) {
 export function trustedOriginHostnames(options = {}) {
     const names = new Set(LOOPBACK_HOSTNAMES);
     names.add(os.hostname().toLowerCase());
-    for (const addresses of Object.values(os.networkInterfaces())) {
-        for (const address of addresses ?? [])
-            names.add(address.address.toLowerCase());
-    }
+    for (const address of interfaceAddresses())
+        names.add(address);
     const proxyUrl = options.proxyUrl ?? process.env.PROXY_URL;
     for (const origin of [proxyUrl, ...(options.trustedOrigins ?? [])]) {
         const hostname = origin ? originHostname(origin) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-gui-interface",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging, request guard",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -19,7 +19,6 @@
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc --watch",
-    "release": "npm version patch && npm run build && npm publish --access public && git push origin master --follow-tags",
     "test": "npm run build && node --test test/*.test.mjs"
   },
   "keywords": [
@@ -34,7 +33,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Matthieu-Pesnot-Pin/mcp-gui-interface.git"
+    "url": "git+https://github.com/Matthieu-Pesnot-Pin/mcp-gui-interface.git"
   },
   "author": "Matthieu Pesnot-Pin",
   "license": "ISC",