Skip to content

docs: fix four broken README links and the ambiguous catalog-seeding wording #1811

Description

@cliffhall

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.

Metadata

Metadata

Assignees

Labels

v2Issues and PRs for v2

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions