|
| 1 | +# Launcher and config consolidation |
| 2 | + |
| 3 | +This document explains the architecture of the `mcp-inspector` application entrypoints and configuration processing. |
| 4 | + |
| 5 | +## How things used to work (and the challenges) |
| 6 | + |
| 7 | +Previously, the project suffered from split config logic and an unnecessary process boundary for the web server: |
| 8 | + |
| 9 | +1. **Two processes for web and CLI:** The main `mcp-inspector` entrypoint would parse arguments and then `spawn()` a child process for the actual web server (either Vite for dev, or `node dist/server.js` for prod). |
| 10 | +2. **Config via environment variables:** To pass config (like server command, transport, auth token, etc.) from the launcher to the child process, the runner serialized everything into an unwieldy list of environment variables (`MCP_INITIAL_*`, `MCP_ENV_VARS`, etc.). |
| 11 | +3. **Doesn't scale:** Multi-server or complex config required more environment variables and ad-hoc encoding (e.g. JSON in env). This was fragile and easy to get out of sync. |
| 12 | +4. **Config logic split:** Config parsing was duplicated across the web runner, the CLI runner, and the TUI runner. |
| 13 | +5. **Direct launch was inconsistent:** Running `npm run dev` or calling a client's binary directly skipped parts of the launcher logic, leading to inconsistent behavior. |
| 14 | + |
| 15 | +## How things work now (Current Design) |
| 16 | + |
| 17 | +The architecture is now consolidated into a single-process model with a shared configuration processor. |
| 18 | + |
| 19 | +### 1. Dedicated Launcher |
| 20 | + |
| 21 | +A dedicated package under `clients/launcher/` (`src/index.ts` → `build/index.js`) serves as the global `mcp-inspector` binary. |
| 22 | + |
| 23 | +- **Responsibility:** Its only job is to choose which app to run (`--web`, `--cli`, or `--tui`) and to forward `process.argv`. |
| 24 | +- **No spawn:** It dynamically imports the chosen app's runner and calls it **in-process**. |
| 25 | + |
| 26 | +### 2. Shared Config Processor |
| 27 | + |
| 28 | +All configuration parsing and merging rules live in **core** (`core/mcp/node/config.ts`). |
| 29 | + |
| 30 | +- **Input:** Parsed argument options (file path, server name, env vars, transport, headers) and a mode (`single` or `multi`). |
| 31 | +- **Output:** A list of `MCPServerConfig` objects. |
| 32 | +- **Benefits:** Web, CLI, and TUI all share the exact same rules for loading config files, applying command-line overrides, and resolving environment variables. |
| 33 | + |
| 34 | +### 3. App Runners |
| 35 | + |
| 36 | +Each app (Web, CLI, TUI) exposes a **runner** function (`runWeb(argv)`, `runCli(argv)`, `runTui(argv)`). |
| 37 | + |
| 38 | +- The runner uses Commander to parse the arguments. |
| 39 | +- It calls the shared core config processor with the relevant server-config subset. |
| 40 | +- It receives the config list and starts the application logic. |
| 41 | +- Direct launch (e.g. `node clients/cli/build/index.js`, or a client's own `npm run dev`) just imports the runner and passes `process.argv`. This guarantees identical behavior whether invoked via the launcher or directly. v2 ships a single `mcp-inspector` bin; there are no longer per-client binaries. |
| 42 | + |
| 43 | +### 4. Web Server In-Process (Config as Object) |
| 44 | + |
| 45 | +The web app no longer uses `spawn()` or environment variable handoffs. The runner process **is** the web server. |
| 46 | + |
| 47 | +- **WebServerConfig Object:** The runner builds a typed `WebServerConfig` object (containing port, initial MCP config, auth, etc.) and passes it directly to the server. |
| 48 | +- **Vite Dev:** `startViteDevServer(config)` uses Vite's Node API (`createServer` from `vite`) in the same process. It passes the config directly to the Hono Vite plugin via `honoMiddlewarePlugin(config)`. |
| 49 | +- **Hono Prod:** `startHonoServer(config)` starts the production server in the same process. |
| 50 | +- **Benefits:** |
| 51 | + - **Simpler & Scalable:** No env var encoding/decoding. Multi-server config is easily passed as a standard JS object. |
| 52 | + - **Easier debugging:** A single Node process means no spawn/kill plumbing and clear shutdown logic. |
| 53 | + |
| 54 | +### 5. Summary of Execution Flow |
| 55 | + |
| 56 | +| Component | Responsibility | |
| 57 | +| :---------------- | :------------------------------------------------------------------------------------------------------- | |
| 58 | +| **Launcher** | Detects `--web`/`--cli`/`--tui` and calls the app runner in-process. | |
| 59 | +| **Runner** | Parses argv using Commander and calls the core config processor. | |
| 60 | +| **Core Config** | Applies file/cli merging rules, returns `MCPServerConfig` object(s). | |
| 61 | +| **App Execution** | Runner uses the config object to directly start Vite API (dev), Hono API (prod), CLI method, or TUI app. | |
| 62 | + |
| 63 | +## v2 notes |
| 64 | + |
| 65 | +This document was written for v1.5 and describes an architecture that still |
| 66 | +holds on `v2/main`; only the paths moved. Two things worth knowing when reading |
| 67 | +it against the current tree: |
| 68 | + |
| 69 | +- The clients live under `clients/*` (`clients/web`, `clients/cli`, |
| 70 | + `clients/tui`, `clients/launcher`). v2 is **not** an npm workspace — each |
| 71 | + client keeps its own `package.json` and `node_modules`, and shared code in |
| 72 | + `core/` is consumed through the `@inspector/core` build-time alias rather |
| 73 | + than as a dependency. See the [root README](../README.md). |
| 74 | +- The shared config processor gained the `--catalog` (writable) vs. `--config` |
| 75 | + (read-only) split, which the launcher's argument tables and |
| 76 | + [MCP server configuration](./mcp-server-configuration.md) describe. |
0 commit comments