Skip to content

Commit 4d30d1c

Browse files
authored
docs: restore the missing docs/ targets and split the catalog-seeding wording (#1811) (#1812)
Closes #1811 Four README links pointed at files that don't exist on `v2/main`, and the launcher README described catalog seeding as one behavior when it is two. - `docs/mcp-server-configuration.md` — written fresh for v2 (the v1.5 file predates the `--catalog`/`--config` split) - `docs/launcher-config-consolidation-plan.md` — restored from `v1.5/main`, path drift corrected, v2 notes appended - `docs/images/tui-screenshot.png` — regenerated against the current TUI - launcher README seeding wording — split into the two real behaviors (web seeds two sample servers; cli/tui seed empty) Review across three rounds also corrected several claims verified against source: the `--` separator is inverted between web and cli, a cli target placed after a flag is silently discarded, `--server` is a no-op on web and an unknown-option error on tui, the `MCP_CATALOG_PATH` ad-hoc guard is cli-only, and the conflict matrix diverges on both `--header` and `--transport stdio`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD
1 parent de9d8a5 commit 4d30d1c

7 files changed

Lines changed: 361 additions & 57 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,11 @@ inspector/
4545
Each client has its own README with client-specific detail:
4646
[web](./clients/web/README.md) · [cli](./clients/cli/README.md) · [tui](./clients/tui/README.md) · [launcher](./clients/launcher/README.md).
4747

48-
Task-oriented guides live under [`docs/`](./docs) — see [Reviewing an MCP App](./docs/mcp-app-review.md), the CLI-first → one-shot-web recipe for automated App-tool review: `--app-info` probe → deep-link navigate → rendered widget, plus OAuth handoff and proxy support.
48+
Task-oriented guides live under [`docs/`](./docs):
49+
50+
- [MCP server configuration](./docs/mcp-server-configuration.md) — which server(s) the Inspector connects to: `--catalog` vs. `--config`, ad-hoc targets, the `--` separator, the file format and its Inspector-specific per-server fields. Shared by all three clients; the cli and tui READMEs delegate their server-options sections to it.
51+
- [Reviewing an MCP App](./docs/mcp-app-review.md) — the CLI-first → one-shot-web recipe for automated App-tool review: `--app-info` probe → deep-link navigate → rendered widget, plus OAuth handoff and proxy support.
52+
- [Launcher and config consolidation](./docs/launcher-config-consolidation-plan.md) — why the launcher runs a client in-process rather than spawning it, and how the shared config processor fits in.
4953

5054
## Setup
5155

‎clients/cli/README.md‎

Lines changed: 49 additions & 42 deletions
Large diffs are not rendered by default.

‎clients/launcher/README.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,22 @@ editable (see [specification/v2_catalog_launch_config.md](../../specification/v2
1919

2020
| Invocation | Server list | Editable in UI? |
2121
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------- |
22-
| `mcp-inspector --web` | Default catalog `~/.mcp-inspector/mcp.json` | Yes |
23-
| `mcp-inspector --web --catalog <path>` (or `MCP_CATALOG_PATH=<path>`) | That file as the active catalog (created/seeded if missing) | Yes |
22+
| `mcp-inspector --web` | Default catalog `~/.mcp-inspector/mcp.json` (seeded with the two sample servers if missing) | Yes |
23+
| `mcp-inspector --web --catalog <path>` (or `MCP_CATALOG_PATH=<path>`) | That file as the active catalog (same seed-if-missing behavior) | Yes |
2424
| `mcp-inspector --web --config <path>` | That file as a **read-only session** — shown but never written, seeded, or migrated (safe for a foreign config) | No |
2525
| `mcp-inspector --web --server-url <url> --transport http --header "Name: Value"` (or a positional command) | One ad-hoc server held in memory, connectable with the given `--header`s | No |
2626

2727
Rules: `--catalog` and `--config` are mutually exclusive; neither combines with
2828
an ad-hoc target or `--header`; `--header` requires an ad-hoc HTTP/SSE server
2929
and is applied to that connection (it is no longer a warn-only no-op).
3030

31+
**Seed contents are web-specific.** When the web backend creates a missing
32+
writable catalog it seeds `DEFAULT_SEED_CONFIG` (`core/mcp/serverList.ts`) — a
33+
`filesystem-server-default` scoped to `/tmp` plus the canonical
34+
`everything-server-default` — so a first launch has something to connect to.
35+
The CLI and TUI seed an **empty** catalog instead; see the next section. A
36+
read-only `--config` is never seeded on any surface.
37+
3138
## CLI and TUI server-list flags (`--cli` / `--tui`)
3239

3340
The CLI and TUI use the same `--catalog` / `--config` vocabulary as `--web`,
@@ -40,6 +47,11 @@ resolved by the shared `core/mcp/node/config.ts` helpers:
4047
| `--config <path>` | That file as a **read-only session** — served as-is, never written or seeded; **errors if absent** |
4148
| positional command / `--server-url <url>` | One ad-hoc server |
4249

50+
Note the seed contrast with `--web` above: the CLI and TUI write an **empty**
51+
`{ "mcpServers": {} }` (`seedEmptyCatalog` in `core/mcp/node/config.ts`), not
52+
the web client's two sample servers — they are non-interactive or list-driven,
53+
so sample entries would be noise rather than a starting point.
54+
4355
Rules (shared `serverSourceConflict`): `--catalog` and `--config` are mutually
4456
exclusive, and neither combines with an ad-hoc command/URL target. The CLI/TUI
4557
do not perform catalog CRUD yet — they are read consumers — so the

‎clients/tui/README.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ flag it uses the default writable catalog `~/.mcp-inspector/mcp.json` (seeded
1919
empty if missing):
2020

2121
```bash
22-
npx @modelcontextprotocol/inspector --tui --catalog mcp.json # writable catalog (seeded if missing)
22+
npx @modelcontextprotocol/inspector --tui --catalog mcp.json # writable catalog (seeded empty if missing)
2323
npx @modelcontextprotocol/inspector --tui --config mcp.json # read-only session (errors if absent)
2424
```
2525

@@ -29,7 +29,7 @@ npx @modelcontextprotocol/inspector --tui --config mcp.json # read-only sessi
2929

3030
### MCP server (which server(s) to connect to)
3131

32-
Options that specify the MCP server(s) (catalog/config file, ad-hoc command/URL, env vars, headers) are shared by the Web, CLI, and TUI and are documented in [MCP server configuration](../../docs/mcp-server-configuration.md): `--catalog` (writable catalog, seeded if missing; default `~/.mcp-inspector/mcp.json` or `MCP_CATALOG_PATH`), `--config` (read-only session, errors if absent), `-e`, `--cwd`, `--header`, `--transport`, `--server-url`, and the positional `[target...]`. `--catalog` and `--config` are mutually exclusive, and neither combines with an ad-hoc target.
32+
Options that specify the MCP server(s) (catalog/config file, ad-hoc command/URL, env vars, headers) are shared by the Web, CLI, and TUI and are documented in [MCP server configuration](../../docs/mcp-server-configuration.md): `--catalog` (writable catalog, seeded **empty** if missing; default `~/.mcp-inspector/mcp.json` or `MCP_CATALOG_PATH`), `--config` (read-only session, errors if absent), `-e`, `--cwd`, `--header`, `--transport`, `--server-url`, and the positional `[target...]`. `--catalog` and `--config` are mutually exclusive, and neither combines with an ad-hoc target.
3333

3434
### TUI-specific (OAuth for HTTP servers)
3535

@@ -39,9 +39,9 @@ The TUI supports OAuth for **SSE** and **Streamable HTTP** servers. Per-server O
3939

4040
The TUI starts a small loopback HTTP server to receive the authorization redirect after you sign in in the browser. Defaults:
4141

42-
| Surface | Default callback |
43-
| ------- | ---------------- |
44-
| **Web** | `http://localhost:6274/oauth/callback` (main app server) |
42+
| Surface | Default callback |
43+
| ------- | ------------------------------------------------------------------------------------------------- |
44+
| **Web** | `http://localhost:6274/oauth/callback` (main app server) |
4545
| **TUI** | `http://127.0.0.1:6276/oauth/callback` (dedicated runner port; avoids colliding with web on 6274) |
4646

4747
**Why a fixed default port?** Enterprise-managed auth (EMA), CIMD, and many static OAuth apps require **pre-registered redirect URIs**. A predictable default (`http://127.0.0.1:6276/oauth/callback`) lets you register once on the IdP and reuse it across TUI sessions. Dynamic registration (DCR) can use ephemeral ports instead — see below.
@@ -52,13 +52,13 @@ OAuth redirect URIs must match **exactly** what you register on the authorizatio
5252

5353
#### Flags
5454

55-
| Option | Env | Description |
56-
| ------ | --- | ----------- |
57-
| `--client-config <path>` | `MCP_CLIENT_CONFIG_PATH` | Install-level client config (default: `~/.mcp-inspector/storage/client.json`). |
58-
| `--client-id <id>` | — | OAuth client ID (static client); overrides `client.json`. |
59-
| `--client-secret <secret>` | — | OAuth client secret (confidential clients); overrides `client.json`. |
60-
| `--client-metadata-url <url>` | — | Client ID Metadata Document URL (CIMD); overrides `client.json`. |
61-
| `--callback-url <url>` | `MCP_OAUTH_CALLBACK_URL` | OAuth redirect/callback listener (default: `http://127.0.0.1:6276/oauth/callback`). Must bind a **loopback** host (`localhost` / `127.0.0.0/8` / `[::1]`); a non-loopback host hard-errors, since the listener receives the authorization code over plaintext `http`. |
55+
| Option | Env | Description |
56+
| ----------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
57+
| `--client-config <path>` | `MCP_CLIENT_CONFIG_PATH` | Install-level client config (default: `~/.mcp-inspector/storage/client.json`). |
58+
| `--client-id <id>` | — | OAuth client ID (static client); overrides `client.json`. |
59+
| `--client-secret <secret>` | — | OAuth client secret (confidential clients); overrides `client.json`. |
60+
| `--client-metadata-url <url>` | — | Client ID Metadata Document URL (CIMD); overrides `client.json`. |
61+
| `--callback-url <url>` | `MCP_OAUTH_CALLBACK_URL` | OAuth redirect/callback listener (default: `http://127.0.0.1:6276/oauth/callback`). Must bind a **loopback** host (`localhost` / `127.0.0.0/8` / `[::1]`); a non-loopback host hard-errors, since the listener receives the authorization code over plaintext `http`. |
6262

6363
#### Authenticating in the TUI
6464

‎docs/images/tui-screenshot.png‎

178 KB
Loading
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
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

Comments
 (0)