From d476dc50854f637963791cc9bec9f4d1a8d3f70b Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sun, 6 Sep 2026 23:17:32 -0400 Subject: [PATCH] docs: the catalog is seeded on first read, not at boot Copilot review round 2. The First-run behavior section said the backend writes the seed file "when the backend boots". It does not: the write lives in the `GET /api/servers` handler (`core/mcp/remote/node/server.ts`), so a backend that boots and never serves the list leaves the path untouched. Verified against a prod build with an isolated `MCP_CATALOG_PATH`: after boot + GET / : catalog ABSENT GET /api/servers : 200 after GET /api/servers : catalog EXISTS The section now says so, and picks up two adjacent facts the old wording also left out: the write happens inside the write lock (so a concurrent POST/PUT/DELETE cannot be clobbered), and a read-only `--config` source is never seeded. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_012x3rC3JXU17aW3uSwjPoi5 Signed-off-by: cliffhall --- specification/v2_servers_file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/v2_servers_file.md b/specification/v2_servers_file.md index 02d7b8a2..6576adb8 100644 --- a/specification/v2_servers_file.md +++ b/specification/v2_servers_file.md @@ -76,7 +76,7 @@ Replaces the hardcoded `SEED_SERVERS` in `clients/web/src/App.tsx:47` with a fil ## First-run behavior -If the file does not exist when the backend boots, write a file containing `DEFAULT_SEED_CONFIG`. User immediately sees a non-empty Servers screen and discovers the file by editing one of the seeds. Subsequent boots read whatever the user has saved. The seed set started as the two `SEED_SERVERS` this design replaced and is three as of #2201 — the two local stdio servers plus `example-server-default`, the MCP org's remote feature-reference server over Streamable HTTP, so a first launch can reach a remote server without standing one up. `core/mcp/serverList.ts` is the source of truth for the contents; only the _behavior_ is specified here. +If the file does not exist when the backend first **serves the catalog** — the `GET /api/servers` handler, not boot — write a file containing `DEFAULT_SEED_CONFIG`. Booting the backend alone leaves the path untouched; the write happens on the first read of the list, inside the write lock so a concurrent `POST`/`PUT`/`DELETE` cannot be clobbered by it. A read-only `--config` source is never seeded. User immediately sees a non-empty Servers screen and discovers the file by editing one of the seeds. Subsequent boots read whatever the user has saved. The seed set started as the two `SEED_SERVERS` this design replaced and is three as of #2201 — the two local stdio servers plus `example-server-default`, the MCP org's remote feature-reference server over Streamable HTTP, so a first launch can reach a remote server without standing one up. `core/mcp/serverList.ts` is the source of truth for the contents; only the _behavior_ is specified here. ## Architecture