Summary
Four relative links in the client READMEs point at files that do not exist on v2/main, and the launcher README describes catalog seeding in a way that reads as one behavior when it is actually two.
The broken links
| README |
Link |
Status |
clients/cli/README.md |
../../docs/mcp-server-configuration.md |
missing |
clients/tui/README.md |
../../docs/mcp-server-configuration.md |
missing |
clients/tui/README.md |
../../docs/images/tui-screenshot.png |
missing (broken image at the top of the page) |
clients/launcher/README.md |
../../docs/launcher-config-consolidation-plan.md |
missing |
Why they're broken
All three targets exist on v1.5/main and were never carried over. v1.5/main is not an ancestor of v2/main — the clients were merged across but the repo-root docs/ folder was not, so the READMEs arrived still referencing it. docs/ on v2/main contains only mcp-app-review.md, which was added later and independently.
This is not cosmetic for two of them: both the cli and tui READMEs delegate their entire "MCP server (which server to connect to)" options section to mcp-server-configuration.md rather than documenting --catalog / --config / --server / -e / --cwd / --header / --transport / --server-url / [target...] themselves. Following the link is currently the only way to find that reference, and it 404s — so that flag surface is effectively undocumented in-repo for two of the three clients.
The seeding ambiguity
clients/launcher/README.md describes a missing writable catalog as "created/seeded if missing" in both its --web table and its --cli/--tui table, which reads as one shared behavior. It is two:
- Web seeds
DEFAULT_SEED_CONFIG (core/mcp/serverList.ts) — filesystem-server-default (server-filesystem /tmp) and everything-server-default — so a first launch has something to connect to.
- CLI / TUI seed an empty
{ "mcpServers": {} } (seedEmptyCatalog in core/mcp/node/config.ts).
Verified by running each surface against a throwaway HOME. clients/cli/README.md already says "seeded empty", which is right for the CLI but compounds the confusion when read next to the launcher's undifferentiated wording.
This one has already misled a reader: it produced a wrong claim in the modelcontextprotocol.io Inspector docs (#1803), caught in review.
Proposed fix
- Write a fresh
docs/mcp-server-configuration.md for v2. Do not restore the v1.5 file — it predates the --catalog / --config split (writable-and-seeded vs. read-only-and-errors), MCP_CATALOG_PATH, and the mutual-exclusivity rules, so restoring it verbatim would document a model that no longer exists.
- Restore
docs/launcher-config-consolidation-plan.md from v1.5/main with its path references corrected (launcher/ → clients/launcher/). Its substance — single process, no spawn(), shared config processor in core/mcp/node/config.ts — still holds, and it is the rationale the launcher README's Architecture section points at.
- Regenerate
docs/images/tui-screenshot.png against the current TUI rather than restoring the v1.5 image, which shows an older UI.
- Split the seeding rows in the launcher README so the web and cli/tui behaviors are stated separately, with the seeded contents shown.
Acceptance
- No broken relative links in any README (
README.md, AGENTS.md, clients/*/README.md, docs/*.md).
- The cli and tui READMEs' server-options sections resolve to real content.
- The launcher README states the two seed behaviors distinctly.
Summary
Four relative links in the client READMEs point at files that do not exist on
v2/main, and the launcher README describes catalog seeding in a way that reads as one behavior when it is actually two.The broken links
clients/cli/README.md../../docs/mcp-server-configuration.mdclients/tui/README.md../../docs/mcp-server-configuration.mdclients/tui/README.md../../docs/images/tui-screenshot.pngclients/launcher/README.md../../docs/launcher-config-consolidation-plan.mdWhy they're broken
All three targets exist on
v1.5/mainand were never carried over.v1.5/mainis not an ancestor ofv2/main— the clients were merged across but the repo-rootdocs/folder was not, so the READMEs arrived still referencing it.docs/onv2/maincontains onlymcp-app-review.md, which was added later and independently.This is not cosmetic for two of them: both the cli and tui READMEs delegate their entire "MCP server (which server to connect to)" options section to
mcp-server-configuration.mdrather than documenting--catalog/--config/--server/-e/--cwd/--header/--transport/--server-url/[target...]themselves. Following the link is currently the only way to find that reference, and it 404s — so that flag surface is effectively undocumented in-repo for two of the three clients.The seeding ambiguity
clients/launcher/README.mddescribes a missing writable catalog as "created/seeded if missing" in both its--webtable and its--cli/--tuitable, which reads as one shared behavior. It is two:DEFAULT_SEED_CONFIG(core/mcp/serverList.ts) —filesystem-server-default(server-filesystem /tmp) andeverything-server-default— so a first launch has something to connect to.{ "mcpServers": {} }(seedEmptyCatalogincore/mcp/node/config.ts).Verified by running each surface against a throwaway
HOME.clients/cli/README.mdalready says "seeded empty", which is right for the CLI but compounds the confusion when read next to the launcher's undifferentiated wording.This one has already misled a reader: it produced a wrong claim in the modelcontextprotocol.io Inspector docs (#1803), caught in review.
Proposed fix
docs/mcp-server-configuration.mdfor v2. Do not restore the v1.5 file — it predates the--catalog/--configsplit (writable-and-seeded vs. read-only-and-errors),MCP_CATALOG_PATH, and the mutual-exclusivity rules, so restoring it verbatim would document a model that no longer exists.docs/launcher-config-consolidation-plan.mdfromv1.5/mainwith its path references corrected (launcher/→clients/launcher/). Its substance — single process, nospawn(), shared config processor incore/mcp/node/config.ts— still holds, and it is the rationale the launcher README's Architecture section points at.docs/images/tui-screenshot.pngagainst the current TUI rather than restoring the v1.5 image, which shows an older UI.Acceptance
README.md,AGENTS.md,clients/*/README.md,docs/*.md).