Normalize --catalog / --config across CLI/TUI to match web (#1481), + CLI/TUI --help #1347

Activity

1. cliffhall

   added

   v2Issues and PRs for v2Issues and PRs for v2

   on May 23, 2026
2. cliffhall

   assigned

   cliffhall

   and

   BobDickinson

   and unassigned

   cliffhall

   on May 31, 2026
3. cliffhall commented on Jun 16, 2026

   

   cliffhall

   on Jun 16, 2026

   Last edited by cliffhall

   MemberAuthor

   More actions

   Status: behavior already landed in the #1452 port — but it needs normalizing against the #1481 catalog/session model

   The default-path fallback this issue asks for is already implemented (it came in with the CLI/TUI port, not a dedicated PR):

   • core/mcp/node/config.ts — withDefaultConfigPath() injects getDefaultMcpConfigPath() (~/.mcp-inspector/mcp.json) when there's no --config and no ad-hoc target; resolveLaunchServerConfigs() wraps it.
   • CLI: clients/cli/src/cli.ts:395 → resolveLaunchServerConfigs(...).
   • TUI: clients/tui/src/tui-servers.ts:67 → withDefaultConfigPath(...).
   • Tests in clients/web/src/test/core/mcp/node/config.test.ts cover all three branches (default present → use it; explicit config → unchanged; default absent → error).

   So all three incarnations now resolve to the same ~/.mcp-inspector/mcp.json, which is the "single source of truth" goal this issue and #1481 share. ✅

   However, #1481 (web) introduced a catalog vs. read-only session model that this issue's framing predates, and the CLI/TUI have not been brought in line with it. Normalizing that vocabulary + behavior everywhere is the remaining work.

   The divergence to fix

   Concept	Web (post-#1481)	CLI/TUI (today)
   Writable default-catalog flag	--catalog <path> (or MCP_CATALOG_PATH)	no such flag
   Read-only session file flag	--config <path> (served, never written/seeded/migrated)	--config <path> — but it's the only file flag and carries no read-only semantics
   No-flag default	default catalog, writable, seeded if missing	default path injected into the --config slot, read-only by nature, errors if missing
   Writable/read-only split	yes (writable flag end-to-end)	none

   Concretely:

   1. Vocabulary mismatch. The CLI/TUI helper fills the --config/configPath slot with the default path, yet the code/comments call it the "default catalog path" (config.ts:223,307). Semantically it's playing the web's catalog role through the config flag. There is no --catalog flag in CLI/TUI.
   2. Seed-on-missing differs. Web bootstraps ~/.mcp-inspector/mcp.json on first run; CLI/TUI error with "Config file not found" on a fresh machine. So "same source of truth" isn't a uniform first-run experience.
   3. Help text never updated (an acceptance item of this issue): cli.ts:291 is just .option("--config <path>", "Config file path"), and no CLI/TUI help string mentions the default path.

   What we need to do to normalize --catalog / --config everywhere

   Adopt the #1481 semantics as the single shared model across web, CLI, and TUI:

   • Add --catalog <path> to CLI and TUI (mirroring web): writable catalog source, seed-if-missing, the slot the no-flag default fills.
   • Make --config <path> a read-only session everywhere: served but never written/seeded/migrated — same guarantee that protects a foreign config (e.g. claude_desktop_config.json) in web.
   • Re-point the no-flag default at the --catalog (writable) slot, not the --config slot, in withDefaultConfigPath() — and rename the helper/comments to stop conflating the two (it currently says "catalog" while filling --config).
   • Decide seed-on-missing for CLI/TUI. To truly match web, the writable default catalog should seed on first run rather than erroring. (If we deliberately keep CLI/TUI erroring, document that as an intentional difference.)
   • Thread a writable notion through CLI/TUI resolution so --config vs --catalog actually differ in behavior — this is the shared resolveServerList + writable unification already tracked in CLI: lift config-file headers/timeouts/OAuth into serverSettings (parity with TUI) #1482 / Inspector mcpdo client #1432; this issue should coordinate with those rather than duplicate them.
   • Mutual-exclusion + clear errors for --catalog/--config/ad-hoc combinations, matching the web conflict matrix in run-web.ts.
   • Update CLI/TUI --help to document both flags and the default path (closes this issue's outstanding help-text criterion).
   • Tests for the new CLI/TUI matrix (default catalog used/seeded; --catalog writable; --config read-only & never mutated; conflicts error), mirroring the web run-web resolution-matrix tests.

   Suggested issue hygiene [DONE]

   The original three-branch default-fallback ask is done; what remains is the normalization above. Recommend either re-scoping this issue to "normalize --catalog/--config terminology + behavior across web/CLI/TUI" (and link #1481 as the reference model, #1482/#1432 as the writable-unification dependencies), or closing this as delivered and opening a dedicated normalization issue. Either way the checklist above is the work.

   Reference model: specification/v2_catalog_launch_config.md and the launcher README flag table.
4. cliffhall

   changed the title [-]CLI/TUI: default --config to getDefaultMcpConfigPath() when no flag is given[/-] [+]Normalize --catalog / --config across CLI/TUI to match web (#1481), + CLI/TUI --help[/+] on Jun 19, 2026
5. cliffhall

   linked a pull request that will close this issuefeat(cli,tui): normalize --catalog / --config with web; update --help (#1347) #1499on Jun 19, 2026
6. cliffhall

   added 2 commits that reference this issue on Jun 19, 2026

   test(launcher): add smoke:cli + smoke:tui e2e launcher smokes (#1347)

   ...

   19de571

   feat(cli,tui): normalize --catalog / --config with web; update --help (…

   ...

   73b651f
7. cliffhall

   closed this as completedon Jun 19, 2026
8. cliffhall

   added this to the v2.0.0 milestone on Jul 28, 2026