@imenam/mcp-gui-interface 1.0.11 → 1.0.12

package/README.md

@@ -1,276 +1,327 @@
-# @imenam/mcp-gui-interface
-
-Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, and logging.
-
-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.
-
-**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] …`.
-
----
-
-## Full-stack usage sketch
-
-Typical split:
-
-1. **Master:** `setupLogging`, optional `GuiLauncher` + `start()` when `PROXY_URL` (or your policy) allows.
-2. **GUI worker:** `setupLogging`, `ProxyClient.register`, bind HTTP server to returned port, `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,
-} from "@imenam/mcp-gui-interface";
-```
-
----
-
-## Development
-
-```bash
-npm run build        # tsc → dist/
-npm run build:watch
-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, and logging.
+
+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] …`.
+
+---
+
+## Full-stack usage sketch
+
+Typical split:
+
+1. **Master:** `setupLogging`, optional `GuiLauncher` + `start()` when `PROXY_URL` (or your policy) allows.
+2. **GUI worker:** `setupLogging`, `ProxyClient.register`, bind HTTP server to returned port, `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,
+} from "@imenam/mcp-gui-interface";
+```
+
+---
+
+## Development
+
+```bash
+npm run build        # tsc → dist/
+npm run build:watch
+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)

package/dist/src/app-config.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Resolution of the GUI's mount path / display name from the environment.
+ *
+ * Three variable conventions coexist in the ecosystem, for historical reasons:
+ *
+ *   | Convention        | Used by                                   |
+ *   |-------------------|-------------------------------------------|
+ *   | `APP_*`           | Hono-based MCPs (documentor, design)      |
+ *   | `PROXY_APP_*`     | Express-based MCPs (scraper, ticket, …)   |
+ *   | `GUI_*`           | gitHubMCP                                 |
+ *
+ * `APP_PATH` / `APP_NAME` are now the **canonical** names. The two other
+ * conventions remain accepted as fallbacks, in decreasing priority order
+ * (`APP_*` → `PROXY_APP_*` → `GUI_*`), silently: they are legitimate today and
+ * emitting warnings would pollute every existing deployment's logs.
+ *
+ * ---
+ *
+ * ## `APP_PATH_PREFIX`
+ *
+ * A supervisor (the MCP hub) needs to namespace every GUI it starts, so that
+ * two gateways hosting the same MCP do not fight over the same proxy path
+ * (the proxy answers 409 on a live duplicate). The supervisor, however, does
+ * **not** know the "natural" path an MCP picks for itself — that value lives
+ * in the MCP's own source (`/documentor-gui`, `/ticket-manager`, …) and is
+ * deliberately not something the hub stores or asks the user to type.
+ *
+ * Hence `APP_PATH_PREFIX`: the supervisor writes `APP_PATH_PREFIX=/<slug>` and
+ * the MCP keeps choosing its own path.
+ *
+ * ### The exact rule
+ *
+ * 1. An **explicit** path — any of `APP_PATH`, `PROXY_APP_PATH`, `GUI_PATH`
+ *    set to a non-empty value — is taken **as-is, never prefixed**.
+ * 2. Otherwise the MCP's **natural path** (the default hardcoded in its own
+ *    code, passed here as `fallbackPath`) is prefixed with `APP_PATH_PREFIX`.
+ * 3. Normalisation, applied in both cases: a leading `/` is added if missing,
+ *    runs of `/` are collapsed to one, and a trailing `/` is dropped (`/` alone
+ *    survives). An empty prefix, or a prefix of `/`, has no effect at all.
+ * 4. Prefixing is **idempotent**: a path that already starts with the prefix
+ *    (`/abc123` or `/abc123/…`) is returned unchanged, so resolving twice — for
+ *    instance once by the consumer for its `<base href>` and once inside
+ *    {@link ProxyClient.register} — never yields `/abc123/abc123/…`.
+ *
+ * ### Why rule 1
+ *
+ * Because the operator's word wins. Someone who types `APP_PATH=/whatever`
+ * into an MCP's env block is stating the *final* path they want to see in the
+ * proxy, and has no reason to expect an invisible prefix to be spliced in. The
+ * hub's prefix is an automatic, best-effort namespacing of a value nobody
+ * chose; a hand-written `APP_PATH` is a value somebody chose. Rule 1 also
+ * makes the behaviour trivially predictable — "the prefix applies to the
+ * default path, and only to it" — and leaves a built-in escape hatch: to opt
+ * out of prefixing, set `APP_PATH` explicitly.
+ *
+ * The trade-off is that an MCP whose *own* `.env` already pins
+ * `PROXY_APP_PATH` will not be namespaced by a supervisor. That is the
+ * intended reading of "manual override wins"; a supervisor that needs the
+ * namespace guaranteed must not let such a value through.
+ */
+/** Env var names for the GUI path, in decreasing priority order. */
+export declare const APP_PATH_ENV_VARS: readonly ["APP_PATH", "PROXY_APP_PATH", "GUI_PATH"];
+/** Env var names for the GUI display name, in decreasing priority order. */
+export declare const APP_NAME_ENV_VARS: readonly ["APP_NAME", "PROXY_APP_NAME", "GUI_NAME"];
+/** Env var holding the namespace prefix applied to the natural path. */
+export declare const APP_PATH_PREFIX_ENV_VAR = "APP_PATH_PREFIX";
+/** Env var holding the proxy dashboard group label. */
+export declare const APP_GROUP_ENV_VAR = "APP_GROUP";
+type Env = Record<string, string | undefined>;
+/**
+ * Normalises a mount path: leading `/`, no duplicate `/`, no trailing `/`.
+ * An empty input yields `"/"`.
+ */
+export declare function normalizeAppPath(value: string | undefined | null): string;
+/**
+ * Normalises a prefix. Returns `""` when the prefix is absent, empty or `/`,
+ * i.e. when it must have no effect.
+ */
+export declare function normalizeAppPathPrefix(value: string | undefined | null): string;
+/**
+ * Prefixes `path` with `prefix` (see the module docblock for the exact rule).
+ * Idempotent: a path already under the prefix is returned unchanged.
+ */
+export declare function applyAppPathPrefix(path: string, prefix: string | undefined | null): string;
+/** Detailed outcome of {@link resolveAppPath}, for logging or diagnostics. */
+export interface ResolvedAppPath {
+    /** The path to register with the proxy and to use as `<base href>`. */
+    path: string;
+    /** Name of the env var the path came from, when it was set explicitly. */
+    source?: (typeof APP_PATH_ENV_VARS)[number];
+    /** Normalised prefix actually in play (`""` when none). */
+    prefix: string;
+    /** Whether {@link prefix} was applied to {@link path}. */
+    prefixed: boolean;
+}
+/**
+ * Resolves the GUI mount path.
+ *
+ * @param fallbackPath The MCP's natural path, hardcoded in its own source
+ *                     (e.g. `/documentor-gui`). Only this value gets prefixed.
+ * @param env          Environment to read (defaults to `process.env`).
+ */
+export declare function resolveAppPathDetailed(fallbackPath: string, env?: Env): ResolvedAppPath;
+/** Shorthand for {@link resolveAppPathDetailed}().path. */
+export declare function resolveAppPath(fallbackPath: string, env?: Env): string;
+/**
+ * Resolves the GUI display name from `APP_NAME` → `PROXY_APP_NAME` →
+ * `GUI_NAME`, falling back to `fallbackName`.
+ */
+export declare function resolveAppName(fallbackName: string | undefined, env?: Env): string | undefined;
+/**
+ * Resolves the proxy dashboard group from `APP_GROUP`. An empty or
+ * whitespace-only value means "ungrouped" and yields `undefined`.
+ */
+export declare function resolveAppGroup(env?: Env): string | undefined;
+export {};

package/dist/src/app-config.js

@@ -0,0 +1,161 @@
+/**
+ * Resolution of the GUI's mount path / display name from the environment.
+ *
+ * Three variable conventions coexist in the ecosystem, for historical reasons:
+ *
+ *   | Convention        | Used by                                   |
+ *   |-------------------|-------------------------------------------|
+ *   | `APP_*`           | Hono-based MCPs (documentor, design)      |
+ *   | `PROXY_APP_*`     | Express-based MCPs (scraper, ticket, …)   |
+ *   | `GUI_*`           | gitHubMCP                                 |
+ *
+ * `APP_PATH` / `APP_NAME` are now the **canonical** names. The two other
+ * conventions remain accepted as fallbacks, in decreasing priority order
+ * (`APP_*` → `PROXY_APP_*` → `GUI_*`), silently: they are legitimate today and
+ * emitting warnings would pollute every existing deployment's logs.
+ *
+ * ---
+ *
+ * ## `APP_PATH_PREFIX`
+ *
+ * A supervisor (the MCP hub) needs to namespace every GUI it starts, so that
+ * two gateways hosting the same MCP do not fight over the same proxy path
+ * (the proxy answers 409 on a live duplicate). The supervisor, however, does
+ * **not** know the "natural" path an MCP picks for itself — that value lives
+ * in the MCP's own source (`/documentor-gui`, `/ticket-manager`, …) and is
+ * deliberately not something the hub stores or asks the user to type.
+ *
+ * Hence `APP_PATH_PREFIX`: the supervisor writes `APP_PATH_PREFIX=/<slug>` and
+ * the MCP keeps choosing its own path.
+ *
+ * ### The exact rule
+ *
+ * 1. An **explicit** path — any of `APP_PATH`, `PROXY_APP_PATH`, `GUI_PATH`
+ *    set to a non-empty value — is taken **as-is, never prefixed**.
+ * 2. Otherwise the MCP's **natural path** (the default hardcoded in its own
+ *    code, passed here as `fallbackPath`) is prefixed with `APP_PATH_PREFIX`.
+ * 3. Normalisation, applied in both cases: a leading `/` is added if missing,
+ *    runs of `/` are collapsed to one, and a trailing `/` is dropped (`/` alone
+ *    survives). An empty prefix, or a prefix of `/`, has no effect at all.
+ * 4. Prefixing is **idempotent**: a path that already starts with the prefix
+ *    (`/abc123` or `/abc123/…`) is returned unchanged, so resolving twice — for
+ *    instance once by the consumer for its `<base href>` and once inside
+ *    {@link ProxyClient.register} — never yields `/abc123/abc123/…`.
+ *
+ * ### Why rule 1
+ *
+ * Because the operator's word wins. Someone who types `APP_PATH=/whatever`
+ * into an MCP's env block is stating the *final* path they want to see in the
+ * proxy, and has no reason to expect an invisible prefix to be spliced in. The
+ * hub's prefix is an automatic, best-effort namespacing of a value nobody
+ * chose; a hand-written `APP_PATH` is a value somebody chose. Rule 1 also
+ * makes the behaviour trivially predictable — "the prefix applies to the
+ * default path, and only to it" — and leaves a built-in escape hatch: to opt
+ * out of prefixing, set `APP_PATH` explicitly.
+ *
+ * The trade-off is that an MCP whose *own* `.env` already pins
+ * `PROXY_APP_PATH` will not be namespaced by a supervisor. That is the
+ * intended reading of "manual override wins"; a supervisor that needs the
+ * namespace guaranteed must not let such a value through.
+ */
+/** Env var names for the GUI path, in decreasing priority order. */
+export const APP_PATH_ENV_VARS = [
+    "APP_PATH",
+    "PROXY_APP_PATH",
+    "GUI_PATH",
+];
+/** Env var names for the GUI display name, in decreasing priority order. */
+export const APP_NAME_ENV_VARS = [
+    "APP_NAME",
+    "PROXY_APP_NAME",
+    "GUI_NAME",
+];
+/** Env var holding the namespace prefix applied to the natural path. */
+export const APP_PATH_PREFIX_ENV_VAR = "APP_PATH_PREFIX";
+/** Env var holding the proxy dashboard group label. */
+export const APP_GROUP_ENV_VAR = "APP_GROUP";
+function firstNonEmpty(names, env) {
+    for (const name of names) {
+        const raw = env[name];
+        if (typeof raw === "string" && raw.trim() !== "")
+            return raw.trim();
+    }
+    return undefined;
+}
+/**
+ * Normalises a mount path: leading `/`, no duplicate `/`, no trailing `/`.
+ * An empty input yields `"/"`.
+ */
+export function normalizeAppPath(value) {
+    const trimmed = (value ?? "").trim();
+    if (trimmed === "")
+        return "/";
+    const withLeading = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    const collapsed = withLeading.replace(/\/{2,}/g, "/");
+    const withoutTrailing = collapsed.replace(/\/+$/, "");
+    return withoutTrailing === "" ? "/" : withoutTrailing;
+}
+/**
+ * Normalises a prefix. Returns `""` when the prefix is absent, empty or `/`,
+ * i.e. when it must have no effect.
+ */
+export function normalizeAppPathPrefix(value) {
+    const normalized = normalizeAppPath(value);
+    return normalized === "/" ? "" : normalized;
+}
+/**
+ * Prefixes `path` with `prefix` (see the module docblock for the exact rule).
+ * Idempotent: a path already under the prefix is returned unchanged.
+ */
+export function applyAppPathPrefix(path, prefix) {
+    const normalizedPath = normalizeAppPath(path);
+    const normalizedPrefix = normalizeAppPathPrefix(prefix);
+    if (normalizedPrefix === "")
+        return normalizedPath;
+    if (normalizedPath === "/")
+        return normalizedPrefix;
+    if (normalizedPath === normalizedPrefix ||
+        normalizedPath.startsWith(`${normalizedPrefix}/`)) {
+        return normalizedPath;
+    }
+    return `${normalizedPrefix}${normalizedPath}`;
+}
+/**
+ * Resolves the GUI mount path.
+ *
+ * @param fallbackPath The MCP's natural path, hardcoded in its own source
+ *                     (e.g. `/documentor-gui`). Only this value gets prefixed.
+ * @param env          Environment to read (defaults to `process.env`).
+ */
+export function resolveAppPathDetailed(fallbackPath, env = process.env) {
+    const prefix = normalizeAppPathPrefix(env[APP_PATH_PREFIX_ENV_VAR]);
+    for (const name of APP_PATH_ENV_VARS) {
+        const raw = env[name];
+        if (typeof raw === "string" && raw.trim() !== "") {
+            // Rule 1: an operator-set path is final — never prefixed.
+            return { path: normalizeAppPath(raw), source: name, prefix, prefixed: false };
+        }
+    }
+    const natural = normalizeAppPath(fallbackPath);
+    const path = applyAppPathPrefix(natural, prefix);
+    return { path, prefix, prefixed: path !== natural };
+}
+/** Shorthand for {@link resolveAppPathDetailed}().path. */
+export function resolveAppPath(fallbackPath, env = process.env) {
+    return resolveAppPathDetailed(fallbackPath, env).path;
+}
+/**
+ * Resolves the GUI display name from `APP_NAME` → `PROXY_APP_NAME` →
+ * `GUI_NAME`, falling back to `fallbackName`.
+ */
+export function resolveAppName(fallbackName, env = process.env) {
+    return firstNonEmpty(APP_NAME_ENV_VARS, env) ?? fallbackName;
+}
+/**
+ * Resolves the proxy dashboard group from `APP_GROUP`. An empty or
+ * whitespace-only value means "ungrouped" and yields `undefined`.
+ */
+export function resolveAppGroup(env = process.env) {
+    const raw = env[APP_GROUP_ENV_VAR];
+    return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : undefined;
+}

package/dist/src/index.d.ts

@@ -1,5 +1,6 @@
 export { GuiLauncher, reconnectGuiToolDefinition, type GuiLauncherOptions, } from "./gui-launcher.js";
 export { ProxyClient, type RegisterOptions, type RegisterResult } from "./proxy-client.js";
+export { APP_GROUP_ENV_VAR, APP_NAME_ENV_VARS, APP_PATH_ENV_VARS, APP_PATH_PREFIX_ENV_VAR, applyAppPathPrefix, normalizeAppPath, normalizeAppPathPrefix, resolveAppGroup, resolveAppName, resolveAppPath, resolveAppPathDetailed, type ResolvedAppPath, } from "./app-config.js";
 export { IpcHub, type IpcMessage } from "./ipc-hub.js";
 export { setupLogging, createLogger } from "./logger.js";
 export type { ProxyConfig, Logger, SetupLoggingOptions, GuiRuntimeStatus, ReconnectResult, McpToolResult, } from "./types.js";

package/dist/src/index.js

@@ -1,4 +1,5 @@
 export { GuiLauncher, reconnectGuiToolDefinition, } from "./gui-launcher.js";
 export { ProxyClient } from "./proxy-client.js";
+export { APP_GROUP_ENV_VAR, APP_NAME_ENV_VARS, APP_PATH_ENV_VARS, APP_PATH_PREFIX_ENV_VAR, applyAppPathPrefix, normalizeAppPath, normalizeAppPathPrefix, resolveAppGroup, resolveAppName, resolveAppPath, resolveAppPathDetailed, } from "./app-config.js";
 export { IpcHub } from "./ipc-hub.js";
 export { setupLogging, createLogger } from "./logger.js";

package/dist/src/proxy-client.js

@@ -1,6 +1,11 @@
 import http from "http";
 import { createLogger } from "./logger.js";
+import { resolveAppGroup, resolveAppName, resolveAppPathDetailed, } from "./app-config.js";
 const logger = createLogger("ProxyClient");
+/** `http://host:3000/` + `/abc/gui` → `http://host:3000/abc/gui`. */
+function joinPublicUrl(proxyUrl, path) {
+    return `${proxyUrl.replace(/\/+$/, "")}${path}`;
+}
 export class ProxyClient {
     proxyUrl;
     registeredPath;
@@ -12,15 +17,31 @@ export class ProxyClient {
         return this.status;
     }
     async register(options) {
-        this.registeredPath = options.path;
+        // `options.path` is the MCP's natural path. The canonical APP_PATH (or its
+        // PROXY_APP_PATH / GUI_PATH fallbacks) overrides it; APP_PATH_PREFIX
+        // namespaces it. See ./app-config.ts for the exact rule. Resolution is
+        // idempotent, so a consumer that already resolved the path itself (to
+        // build its <base href>, say) can pass the resolved value back in safely.
+        const resolved = resolveAppPathDetailed(options.path);
+        const finalPath = resolved.path;
+        if (finalPath !== options.path) {
+            logger.info(`Mount path resolved to ${finalPath} (requested: ${options.path}${resolved.source ? `, from ${resolved.source}` : ""}${resolved.prefixed ? `, prefixed with ${resolved.prefix}` : ""})`);
+        }
+        this.registeredPath = finalPath;
         // 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 rawGroup = options.group ?? resolveAppGroup();
         const group = typeof rawGroup === "string" && rawGroup.trim() !== ""
             ? rawGroup.trim()
             : undefined;
-        const payload = { ...options, ...(group ? { group } : {}) };
+        const name = resolveAppName(options.name);
+        const payload = {
+            ...options,
+            path: finalPath,
+            ...(name ? { name } : {}),
+            ...(group ? { group } : {}),
+        };
         return new Promise((resolve) => {
             let url;
             try {
@@ -29,7 +50,7 @@ export class ProxyClient {
             catch {
                 logger.error(`Invalid Proxy URL: ${this.proxyUrl}`);
                 this.status = "error";
-                return resolve({ success: false, port: 0, error: "Invalid Proxy URL" });
+                return resolve({ success: false, port: 0, path: finalPath, error: "Invalid Proxy URL" });
             }
             const timeout = 1000;
             logger.info(`Sending registration request to ${url.href}...`);
@@ -53,37 +74,49 @@ export class ProxyClient {
                                 typeof raw.port === "number") {
                                 logger.info(`Registration verified. Allocated port: ${raw.port}`);
                                 this.status = "connected";
-                                resolve({ success: true, port: raw.port, url: raw.url });
+                                resolve({
+                                    success: true,
+                                    port: raw.port,
+                                    path: typeof raw.path === "string" && raw.path !== ""
+                                        ? raw.path
+                                        : finalPath,
+                                    // The proxy does not return a public URL; synthesise it
+                                    // from the path it actually mounted, so consumers stop
+                                    // rebuilding it from their own (unprefixed) path.
+                                    url: typeof raw.url === "string" && raw.url !== ""
+                                        ? raw.url
+                                        : joinPublicUrl(this.proxyUrl, finalPath),
+                                });
                             }
                             else {
                                 logger.error(`Invalid proxy response schema: ${data}`);
                                 this.status = "error";
-                                resolve({ success: false, port: 0, error: "Invalid proxy response schema" });
+                                resolve({ success: false, port: 0, path: finalPath, error: "Invalid proxy response schema" });
                             }
                         }
                         catch {
                             logger.error(`JSON parse error: ${data}`);
                             this.status = "error";
-                            resolve({ success: false, port: 0, error: "Invalid JSON response" });
+                            resolve({ success: false, port: 0, path: finalPath, error: "Invalid JSON response" });
                         }
                     }
                     else {
                         logger.error(`Registration rejected with HTTP ${res.statusCode}`);
                         this.status = "error";
-                        resolve({ success: false, port: 0, error: `HTTP ${res.statusCode}` });
+                        resolve({ success: false, port: 0, path: finalPath, error: `HTTP ${res.statusCode}` });
                     }
                 });
             });
             req.on("error", (err) => {
                 logger.error(`Registration error: ${err.message}`);
                 this.status = "error";
-                resolve({ success: false, port: 0, error: err.message });
+                resolve({ success: false, port: 0, path: finalPath, error: err.message });
             });
             req.on("timeout", () => {
                 logger.error(`Registration timeout after ${timeout}ms`);
                 req.destroy();
                 this.status = "error";
-                resolve({ success: false, port: 0, error: "Timeout" });
+                resolve({ success: false, port: 0, path: finalPath, error: "Timeout" });
             });
             req.write(JSON.stringify(payload));
             req.end();

package/dist/src/types.d.ts

@@ -14,13 +14,31 @@ export interface ProxyConfig {
 export interface RegisterResult {
     success: boolean;
     port: number;
+    /**
+     * Path the GUI was actually registered under, after `APP_PATH` /
+     * `PROXY_APP_PATH` / `GUI_PATH` and `APP_PATH_PREFIX` were applied to the
+     * requested path (see `app-config.ts`). Use it — not the path you passed in —
+     * to build the SPA's `<base href>` and any public URL.
+     */
+    path?: string;
     url?: string;
     error?: string;
 }
 export interface RegisterOptions {
+    /**
+     * The MCP's **natural** mount path (its own hardcoded default, e.g.
+     * `/documentor-gui`). `register()` resolves the final path from it: an
+     * explicit `APP_PATH` / `PROXY_APP_PATH` / `GUI_PATH` replaces it, otherwise
+     * `APP_PATH_PREFIX` is prepended to it. Resolution is idempotent, and the
+     * effective path comes back in {@link RegisterResult.path}.
+     */
     path: string;
-    name?: string;
     port?: number;
+    /**
+     * Display name. Overridden by `APP_NAME` / `PROXY_APP_NAME` / `GUI_NAME`
+     * when one of them is set.
+     */
+    name?: string;
     /**
      * Optional visual group. The proxy dashboard places every app sharing the
      * same `group` under one collapsible section (folded by default). Apps left

package/package.json

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