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
This commit is contained in:
Cliff Hall 2026-07-27 20:37:14 -04:00 • committed by GitHub
commit 4d30d1cd1e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -19,8 +19,8 @@ editable (see [specification/v2_catalog_launch_config.md](../../specification/v2
| Invocation | Server list | Editable in UI? |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------- |
| `mcp-inspector --web` | Default catalog `~/.mcp-inspector/mcp.json` | Yes |
| `mcp-inspector --web --catalog <path>` (or `MCP_CATALOG_PATH=<path>`) | That file as the active catalog (created/seeded if missing) | Yes |
| `mcp-inspector --web` | Default catalog `~/.mcp-inspector/mcp.json` (seeded with the two sample servers if missing) | Yes |
| `mcp-inspector --web --catalog <path>` (or `MCP_CATALOG_PATH=<path>`) | That file as the active catalog (same seed-if-missing behavior) | Yes |
| `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 |
| `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 |
@ -28,6 +28,13 @@ Rules: `--catalog` and `--config` are mutually exclusive; neither combines with
an ad-hoc target or `--header`; `--header` requires an ad-hoc HTTP/SSE server
and is applied to that connection (it is no longer a warn-only no-op).
**Seed contents are web-specific.** When the web backend creates a missing
writable catalog it seeds `DEFAULT_SEED_CONFIG` (`core/mcp/serverList.ts`) — a
`filesystem-server-default` scoped to `/tmp` plus the canonical
`everything-server-default` — so a first launch has something to connect to.
The CLI and TUI seed an **empty** catalog instead; see the next section. A
read-only `--config` is never seeded on any surface.
## CLI and TUI server-list flags (`--cli` / `--tui`)
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:
| `--config <path>` | That file as a **read-only session** — served as-is, never written or seeded; **errors if absent** |
| positional command / `--server-url <url>` | One ad-hoc server |
Note the seed contrast with `--web` above: the CLI and TUI write an **empty**
`{ "mcpServers": {} }` (`seedEmptyCatalog` in `core/mcp/node/config.ts`), not
the web client's two sample servers — they are non-interactive or list-driven,
so sample entries would be noise rather than a starting point.
Rules (shared `serverSourceConflict`): `--catalog` and `--config` are mutually
exclusive, and neither combines with an ad-hoc command/URL target. The CLI/TUI
do not perform catalog CRUD yet — they are read consumers — so the