@codewizard-dt/bootstrap 2.10.0 → 2.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +20 -7
  2. package/lib/README.md +1 -1
  3. package/lib/hooks/README.md +13 -12
  4. package/lib/prompts/setup-strict-typechecks.md +1 -1
  5. package/lib/scripts/README.md +3 -1
  6. package/lib/scripts/build-mcp-guide.sh +1 -1
  7. package/lib/scripts/install-global.sh +7 -1
  8. package/lib/scripts/install-mcps.sh +176 -13
  9. package/lib/scripts/lib.sh +16 -0
  10. package/lib/scripts/merge-settings-deny.js +124 -0
  11. package/lib/scripts/setup-project.sh +16 -3
  12. package/lib/scripts/templates/guides/stubs/playwright.md +1 -1
  13. package/lib/scripts/templates/settings-deny.json +38 -0
  14. package/lib/skills/anti-slop/SKILL.md +1 -1
  15. package/lib/skills/bug-close/SKILL.md +1 -1
  16. package/lib/skills/bug-file/SKILL.md +1 -1
  17. package/lib/skills/bug-triage/SKILL.md +1 -1
  18. package/lib/skills/company-align/SKILL.md +1 -1
  19. package/lib/skills/debug-logs/SKILL.md +1 -1
  20. package/lib/skills/decision-create/SKILL.md +2 -2
  21. package/lib/skills/decision-finalize/SKILL.md +1 -1
  22. package/lib/skills/decision-walkthrough/SKILL.md +1 -1
  23. package/lib/skills/demo/SKILL.md +1 -1
  24. package/lib/skills/elevator-pitch/SKILL.md +1 -1
  25. package/lib/skills/eval-create/SKILL.md +1 -1
  26. package/lib/skills/eval-gap/SKILL.md +1 -1
  27. package/lib/skills/eval-run/SKILL.md +1 -1
  28. package/lib/skills/extract-feature/SKILL.md +1 -1
  29. package/lib/skills/flashcard/SKILL.md +1 -1
  30. package/lib/skills/frontend-taste/SKILL.md +1 -1
  31. package/lib/skills/gap-assess/SKILL.md +1 -1
  32. package/lib/skills/lint/SKILL.md +1 -1
  33. package/lib/skills/marp-slideshow/SKILL.md +1 -1
  34. package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
  35. package/lib/skills/now/SKILL.md +1 -1
  36. package/lib/skills/port-feature/SKILL.md +1 -1
  37. package/lib/skills/power-mode/SKILL.md +1 -1
  38. package/lib/skills/project-readme/SKILL.md +1 -1
  39. package/lib/skills/req-compile/SKILL.md +1 -1
  40. package/lib/skills/req-create/SKILL.md +1 -1
  41. package/lib/skills/req-extract-decisions/SKILL.md +1 -1
  42. package/lib/skills/req-finalize/SKILL.md +1 -1
  43. package/lib/skills/req-update/SKILL.md +1 -1
  44. package/lib/skills/research/SKILL.md +1 -1
  45. package/lib/skills/research-company/SKILL.md +2 -2
  46. package/lib/skills/roadmap-create/SKILL.md +1 -1
  47. package/lib/skills/security-audit/SKILL.md +1 -1
  48. package/lib/skills/simplify/SKILL.md +1 -1
  49. package/lib/skills/tackle/SKILL.md +1 -1
  50. package/lib/skills/task-add/SKILL.md +1 -1
  51. package/lib/skills/task-audit/SKILL.md +1 -1
  52. package/lib/skills/task-update/SKILL.md +1 -1
  53. package/lib/skills/uat-auto/SKILL.md +1 -1
  54. package/lib/skills/uat-auto-plus/SKILL.md +1 -1
  55. package/lib/skills/uat-generate/SKILL.md +1 -1
  56. package/lib/skills/uat-walk/SKILL.md +1 -1
  57. package/lib/skills/update-docs/SKILL.md +1 -1
  58. package/lib/skills/wiki-archive/SKILL.md +1 -1
  59. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  60. package/lib/skills/wiki-lint/SKILL.md +1 -1
  61. package/lib/skills/wiki-query/SKILL.md +1 -1
  62. package/lib/skills/wiki-rotate-log/SKILL.md +1 -1
  63. package/lib/skills/wiki-tidy/SKILL.md +1 -1
  64. package/package.json +1 -1
  65. package/raw/research/brave-mcp-single-docker-container/index.md +94 -0
  66. package/raw/research/brave-mcp-single-docker-container/sources.md +70 -0
  67. package/raw/research/mcp-one-process-per-user/index.md +75 -0
  68. package/raw/research/mcp-one-process-per-user/sources.md +66 -0
@@ -0,0 +1,94 @@
1
+ ---
2
+ topic: a setup that only has 1 global (user scoped) brave mcp server via docker, does not require the user to set up the server manually (starts via the command in .claude.json), and uses a named container (remove the rm flag if necessary)
3
+ slug: brave-mcp-single-docker-container
4
+ researched: 2026-07-28
5
+ sources: [./sources.md]
6
+ ---
7
+
8
+ # Research: Single global user-scoped Brave MCP server via a named Docker container, auto-started from `.claude.json`
9
+
10
+ > **Answer:** Register brave-search once at user scope (stored in `~/.claude.json` [S7]) with a small shell wrapper as the server command. The wrapper lazily creates/starts one **persistent named container** (`brave-search-mcp`, no `--rm`, entrypoint overridden to `sleep infinity`) and then `docker exec -i`s a fresh server process (`node dist/index.js` — the image's real entrypoint [S4]) into it for each session. This is necessary because Claude Code spawns the configured stdio command **once per session** [S6] — so "one container" and "one process" cannot both be true for stdio; the exec pattern gives exactly one named container with N short-lived server processes inside it, which is concurrency-safe, needs zero manual setup, and keeps the API key fresh per session.
11
+
12
+ ## Research Questions
13
+
14
+ 1. How does Claude Code launch user-scoped stdio MCP servers — one process per session or shared?
15
+ 2. What does the `docker.io/mcp/brave-search` image actually run (entrypoint, transports, env contract)?
16
+ 3. What command shape yields exactly one named container across sessions with no manual setup — `docker run --name`, `docker start -a` reuse, persistent container + `docker exec`, long-lived HTTP container, or Docker's MCP Gateway?
17
+ 4. Where does the user-scoped config live and does it support env-var handling suitable for the API key?
18
+ 5. What changes versus the current TASK-020 plan (`docker run -i --rm --name`)?
19
+
20
+ ## Current State (Codebase)
21
+
22
+ - `lib/scripts/install-mcps.sh::_add_brave` registers brave-search via `mcp_add_scoped` → `claude mcp add --scope user brave-search --env "BRAVE_API_KEY=${BRAVE_API_KEY}" -- npx -y @modelcontextprotocol/server-brave-search` (project scope also possible interactively) [S1]. `register_optional_mcp` skips if already installed, so the script never double-registers [S1].
23
+ - `lib/scripts/setup-project.sh` echoes matching manual re-add instructions [S1].
24
+ - `wiki/work/tasks/TASK-020-brave-search-mcp-docker.md` (status `todo`, created 2026-07-27) already plans a Docker conversion but as `docker run -i --rm --name brave-search-mcp` — it documents the very defect this research resolves: with `--rm` + a fixed `--name`, two concurrent sessions collide on the container name [S2].
25
+
26
+ ## Key Findings
27
+
28
+ 1. **Claude Code spawns one stdio child process per session.** Every new session runs the configured `command` again; multiple sessions mean multiple concurrent invocations of it [S6]. Any design must tolerate N concurrent invocations.
29
+ 2. **User scope lives in `~/.claude.json`** (top-level `mcpServers`), is cross-project, and is the *lowest*-precedence scope — a local- or project-scoped server with the same name shadows it, so achieving "only 1 global server" also means not registering brave-search at project scope anywhere [S7].
30
+ 3. **The `mcp/brave-search` image is the official `brave/brave-search-mcp-server`.** `ENTRYPOINT ["node", "dist/index.js"]`, `USER node`, `WORKDIR /app` [S4]. Stdio is the default transport; HTTP is available via `BRAVE_MCP_TRANSPORT=http` / `--transport http` (port 8080); the key comes from `BRAVE_API_KEY` (or `BRAVE_API_KEY_FILE`) [S3]. The Docker MCP Catalog's canonical config is `docker run -i --rm -e BRAVE_API_KEY mcp/brave-search` — ephemeral, unnamed-by-default, one container per session [S5].
31
+ 4. **`docker start -a` reuse is not concurrency-safe.** `docker start -ai <name> || docker run -i --name <name>` works for sequential sessions (start revives the stopped container and attaches stdio [S10]), but a second concurrent session attaches to the *same* stdio stream — two JSON-RPC clients multiplexed onto one stdin/stdout with no framing to separate them *(inference — no primary source; follows from stdio MCP having exactly one client per stream)*. Env is also frozen at container-creation time, so key rotation would require deleting the container.
32
+ 5. **Persistent container + `docker exec -i` decouples "one container" from "one process per session".** The container is created once (named, no `--rm`, `--entrypoint sleep … infinity` so it idles), revived with `docker start` when stopped, and each session runs `docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js`. Exec'd processes inherit the image's `WORKDIR`/`USER`, exit on stdin EOF when the session closes, and `-e BRAVE_API_KEY` (value-less) forwards the key fresh from the wrapper's environment each session — which Claude Code populates from the config's `env` block [S4][S7]. `--init` on the `docker run` makes tini PID 1 so orphaned children get reaped *(inference for the reaping rationale; `--init` behavior is standard Docker)*.
33
+ 6. **Docker's MCP Gateway is the official "one entry, many servers" alternative** — Docker Desktop writes `"MCP_DOCKER": {"command": "docker", "args": ["mcp", "gateway", "run"]}` into `~/.claude.json` [S8] — but the gateway names and manages containers itself (no user-chosen container name), requires Docker Desktop's MCP Toolkit, and has open Claude Code timeout issues [S8][S9]. It also still spawns one gateway process per session.
34
+ 7. **A long-lived HTTP container is the only way to get literally one server process**, and third-party images exist that bridge stdio→HTTP precisely to share one backend across sessions [S11]. But an HTTP registration in `~/.claude.json` is just a URL — nothing in the config starts the container, failing the "starts via the command in `.claude.json`" requirement.
35
+
36
+ ## Constraints
37
+
38
+ - Must survive N concurrent Claude Code sessions (each spawning the command) without name collisions or stream corruption.
39
+ - Must be a single user-scope registration; no project-scope duplicates (they would shadow it [S7]).
40
+ - Container must be named (`brave-search-mcp`) and visible/identifiable in Docker Desktop; `--rm` may be dropped.
41
+ - No manual `docker run`/`docker start` by the user — the `.claude.json` command does everything; per prior user decision on TASK-020, no docker-availability guard and no npx fallback [S2].
42
+ - The exec pattern pins the server start command (`node dist/index.js`) — a change to the image's layout would break it; the plain-entrypoint options do not have this coupling [S4].
43
+
44
+ ## Solution Comparison
45
+
46
+ | Option | One named container? | Concurrent sessions | Auto-start from config | Complexity | Notes |
47
+ |--------|---------------------|--------------------|-----------------------|------------|-------|
48
+ | **A. `docker run -i --rm --name`** (TASK-020 plan) | Yes, but ephemeral | ❌ name conflict, 2nd session's MCP fails [S2] | ✅ | Low | Canonical catalog shape + name [S5] |
49
+ | **B. `docker start -ai` ∥ `docker run -i --name` (no `--rm`)** | Yes, persistent | ❌ two clients attach to one stdio stream *(inference)* | ✅ | Low | Env frozen at creation; key rotation needs container delete |
50
+ | **C. Persistent container + `docker exec -i` per session** (recommended) | ✅ exactly one | ✅ one exec'd process per session | ✅ | Medium | Pins `node dist/index.js` [S4]; container idles on `sleep infinity` |
51
+ | **D. Long-lived HTTP container + `--transport http` registration** | ✅ exactly one, one *process* | ✅ | ❌ URL config starts nothing | Medium | Needs one manual/scripted `docker run -d`; best "true single server" if the auto-start constraint relaxes [S3][S11] |
52
+ | **E. Docker MCP Gateway (`docker mcp gateway run`)** | ❌ gateway-managed names | ✅ | ✅ | High (Docker Desktop MCP Toolkit) | Known Claude Code timeout issues [S8][S9]; replaces per-server registration model |
53
+
54
+ ## Recommendation
55
+
56
+ **Option C.** Register once at user scope with a wrapper command; resulting `~/.claude.json` entry:
57
+
58
+ ```json
59
+ "brave-search": {
60
+ "command": "sh",
61
+ "args": [
62
+ "-c",
63
+ "docker start brave-search-mcp >/dev/null 2>&1 || docker run -d --init --name brave-search-mcp --entrypoint sleep docker.io/mcp/brave-search infinity >/dev/null 2>&1; exec docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js"
64
+ ],
65
+ "env": { "BRAVE_API_KEY": "<key>" }
66
+ }
67
+ ```
68
+
69
+ Installer form (replacing `_add_brave`'s command tail in `lib/scripts/install-mcps.sh`):
70
+
71
+ ```bash
72
+ mcp_add_scoped "$1" brave-search \
73
+ --env "BRAVE_API_KEY=${BRAVE_API_KEY}" \
74
+ -- sh -c 'docker start brave-search-mcp >/dev/null 2>&1 || docker run -d --init --name brave-search-mcp --entrypoint sleep docker.io/mcp/brave-search infinity >/dev/null 2>&1; exec docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js'
75
+ ```
76
+
77
+ How it satisfies each requirement:
78
+ - **1 global server** — single `--scope user` registration in `~/.claude.json`; for this goal the installer should force user scope for brave-search (skip the interactive project-scope option) so no project entry shadows it [S7].
79
+ - **No manual setup** — first session creates the container; later sessions `docker start` it if stopped (e.g. after reboot) and exec into it. The API key is never baked into the container — it's forwarded at exec time from the config's `env` block, so rotating the key in `~/.claude.json` takes effect next session.
80
+ - **Named container, no `--rm`** — `brave-search-mcp` persists and is always identifiable in Docker Desktop (running `sleep` when idle).
81
+
82
+ **Risks & mitigations:**
83
+ - *Entrypoint pinning*: `node dist/index.js` comes from the image's Dockerfile [S4]; if upstream changes it, the exec fails visibly in `claude mcp list`. Mitigation: comment in the script citing the Dockerfile; re-verify on image updates.
84
+ - *Image updates*: the persistent container stays on its creation-time image. Update path: `docker rm -f brave-search-mcp && docker pull docker.io/mcp/brave-search` — next session recreates it. Worth an echo line in `setup-project.sh`.
85
+ - *First-run race*: two sessions starting simultaneously with no container — both `docker run -d`, one loses the name race, but the `;` before `exec` means the loser still execs into the winner's container. A sub-second window exists where exec can beat container readiness; in practice Claude Code retries the connection.
86
+ - *Zombie processes*: `sleep` as PID 1 doesn't reap; `--init` (tini) does.
87
+
88
+ **Alternative if constraints change:** if "must start from `.claude.json`" is ever relaxed, Option D (one HTTP-mode container with `--restart unless-stopped`, registered as `--transport http http://localhost:8080/mcp`) is strictly simpler at runtime — literally one server process, no wrapper, no entrypoint pinning [S3].
89
+
90
+ ## Next Steps
91
+
92
+ - **Update TASK-020** rather than file a new task — its `docker run -i --rm --name` plan is superseded by this design: `/task-update wiki/work/tasks/TASK-020-brave-search-mcp-docker.md replace the run command with the persistent-container + docker exec wrapper from raw/research/brave-mcp-single-docker-container/index.md; force user scope for brave-search`
93
+ - `/wiki-ingest raw/research/brave-mcp-single-docker-container/index.md` to synthesize into the knowledge base.
94
+ - Optional follow-up: verify on this machine that `docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js` completes an MCP handshake from two concurrent sessions before landing the installer change.
@@ -0,0 +1,70 @@
1
+ ---
2
+ topic: a setup that only has 1 global (user scoped) brave mcp server via docker, does not require the user to set up the server manually (starts via the command in .claude.json), and uses a named container (remove the rm flag if necessary)
3
+ slug: brave-mcp-single-docker-container
4
+ researched: 2026-07-28
5
+ ---
6
+
7
+ # Primary Sources — Single global Brave MCP server via named Docker container
8
+
9
+ | ID | Type | Locator | Accessed | What it contributed |
10
+ |----|------|---------|----------|---------------------|
11
+ | S1 | codebase | `lib/scripts/install-mcps.sh::_add_brave`, `::mcp_add_scoped`, `::register_optional_mcp` | 2026-07-28 | Current npx-based registration, user/project scope resolution, already-installed skip |
12
+ | S2 | codebase | `wiki/work/tasks/TASK-020-brave-search-mcp-docker.md` | 2026-07-28 | Prior plan (`docker run -i --rm --name brave-search-mcp`) and its documented concurrent-session name-conflict trade-off |
13
+ | S3 | web | https://github.com/brave/brave-search-mcp-server | 2026-07-28 | Env contract (`BRAVE_API_KEY`, `BRAVE_API_KEY_FILE`, `BRAVE_MCP_TRANSPORT`), stdio default, HTTP option, CLI flags |
14
+ | S4 | web | https://raw.githubusercontent.com/brave/brave-search-mcp-server/main/Dockerfile | 2026-07-28 | Image internals: `ENTRYPOINT ["node", "dist/index.js"]`, `USER node`, `WORKDIR /app` — the command a `docker exec` variant must run |
15
+ | S5 | web | https://hub.docker.com/mcp/server/brave/overview | 2026-07-28 | Canonical Docker MCP Catalog config: `docker run -i --rm -e BRAVE_MCP_TRANSPORT -e BRAVE_API_KEY mcp/brave-search` (ephemeral, per-session) |
16
+ | S6 | web | https://github.com/anthropics/claude-code/issues/29688 | 2026-07-28 | Claude Code spawns one stdio MCP child process per session; processes accumulate across sessions |
17
+ | S7 | web | https://code.claude.com/docs/en/mcp | 2026-07-28 | User scope stored in `~/.claude.json`; scope precedence local > project > user; `${VAR}` expansion locations (command, args, env, url, headers) |
18
+ | S8 | web | https://github.com/docker/mcp-gateway/issues/336 | 2026-07-28 | Docker Desktop writes `MCP_DOCKER` = `docker mcp gateway run` into `~/.claude.json`; Claude Code connection timeouts with the gateway |
19
+ | S9 | web | https://github.com/anthropics/claude-code/issues/4202 | 2026-07-28 | Docker MCP Toolkit tool calls time out after 120s in Claude Code despite gateway showing connected |
20
+ | S10 | web | https://www.dash0.com/faq/how-to-start-a-docker-container | 2026-07-28 | `docker start -a` semantics: attaches the terminal to the container's stdout/stderr; `-i` keeps stdin open |
21
+ | S11 | web | https://hub.docker.com/r/mekayelanik/brave-search-mcp | 2026-07-28 | Third-party precedent for sharing one stdio backend across sessions via an HTTP bridge (mcp-proxy stateful mode) |
22
+
23
+ ## Excerpts
24
+
25
+ ### S3 — brave/brave-search-mcp-server (GitHub)
26
+ https://github.com/brave/brave-search-mcp-server
27
+ > BRAVE_API_KEY_FILE: Path to a file containing your Brave Search API key. When set, this takes precedence over BRAVE_API_KEY. Useful for Docker secrets and similar mounted-secret setups. BRAVE_MCP_TRANSPORT: Transport mode ("http" or "stdio", default: "stdio")
28
+
29
+ > To follow established MCP conventions, the server now defaults to STDIO. If you would like to continue using HTTP, you will need to set the BRAVE_MCP_TRANSPORT environment variable to http, or provide the runtime argument --transport http when launching the server.
30
+
31
+ ### S4 — brave-search-mcp-server Dockerfile
32
+ https://raw.githubusercontent.com/brave/brave-search-mcp-server/main/Dockerfile
33
+ > ENTRYPOINT ["node", "dist/index.js"]
34
+ > USER node
35
+ > WORKDIR /app
36
+ (No CMD defined; the server starts via `node dist/index.js` at `/app/dist/index.js`.)
37
+
38
+ ### S5 — Brave Search MCP Server | Docker MCP Catalog
39
+ https://hub.docker.com/mcp/server/brave/overview
40
+ > { "mcpServers": { "brave": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "BRAVE_MCP_TRANSPORT", "-e", "BRAVE_API_KEY", "mcp/brave-search" ], "env": { "BRAVE_MCP_TRANSPORT": "stdio", "BRAVE_API_KEY": "YOUR_API_KEY_HERE" } } } }
41
+
42
+ ### S6 — anthropics/claude-code#29688
43
+ https://github.com/anthropics/claude-code/issues/29688
44
+ > This results in redundant MCP server processes accumulating — one stdio process per Claude Code session, in addition to the shared HTTP server. ... Open more Claude Code sessions — each one spawns another stdio child process
45
+
46
+ ### S7 — Claude Code docs: Connect Claude Code to tools via MCP
47
+ https://code.claude.com/docs/en/mcp
48
+ > User-scoped servers are stored in `~/.claude.json` and provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account.
49
+
50
+ > When there are multiple servers with the same name, Claude Code applies this precedence: 1. Local scope 2. Project scope 3. User scope
51
+
52
+ > Environment variables can be expanded in: `command`: the server executable path; `args`: command-line arguments; `env`: environment variables passed to the server; `url`: for HTTP server types; `headers`: for HTTP server authentication
53
+
54
+ ### S8 — docker/mcp-gateway#336
55
+ https://github.com/docker/mcp-gateway/issues/336
56
+ > I used the button in docker desktop to connect to claude code and I see that it adds the following to my ~/.claude.json · "mcpServers": { "MCP_DOCKER": { "command": "docker", "args": [ "mcp", "gateway", "run" ] } }
57
+
58
+ > When I look in ~/.claude/debug/latest I see 'MCP server "MCP_DOCKER" Connection failed: Connection to MCP server "MCP_DOCKER" timed out after 30000ms'. But if I run docker mcp gateway run on the command line no issues.
59
+
60
+ ### S9 — anthropics/claude-code#4202
61
+ https://github.com/anthropics/claude-code/issues/4202
62
+ > Claude Code fails to execute MCP tools when using Docker Desktop's MCP Toolkit integration. All tool calls timeout after 120 seconds despite Gateway showing as connected.
63
+
64
+ ### S10 — Dash0: How to Start a Docker Container
65
+ https://www.dash0.com/faq/how-to-start-a-docker-container
66
+ > -a (attach) attaches your terminal to the container's stdout and stderr, the same way running without -d does for docker run. ... -i (interactive) keeps stdin open.
67
+
68
+ ### S11 — mekayelanik/brave-search-mcp (Docker Hub)
69
+ https://hub.docker.com/r/mekayelanik/brave-search-mcp
70
+ > mcp-proxy stateful default shares one stdio backend across sessions and reduced RSS by ~4.6× in our fleet testing. ... MCP_PROXY_STATELESS=false (default): one stdio backend child is shared across all MCP sessions, JSON-RPC-id-multiplexed.
@@ -0,0 +1,75 @@
1
+ ---
2
+ topic: a user scoped mcp --- if multiple sessions are active, why does it start a new mcp process for each session? can we enforce one process per user mcp globally?
3
+ slug: mcp-one-process-per-user
4
+ researched: 2026-07-28
5
+ sources: [./sources.md]
6
+ ---
7
+
8
+ # Research: Why user-scoped MCPs spawn one process per session, and whether one global process is enforceable
9
+
10
+ > **Answer, part 1 (why):** it's the MCP protocol's stdio design, not a Claude Code quirk — the spec defines stdio as "the client launches the MCP server as a subprocess" with the process lifecycle bound to that one client (close stdin → terminate) [S3]; there is no in-protocol multiplexing for stdio [S6], and each Claude Code session is an independent MCP client with no shared daemon between sessions — host-level sharing is an **open, unimplemented feature request** (anthropics/claude-code#28860, #40220) [S4][S5]. **Answer, part 2 (can we enforce one process):** yes, but only by leaving stdio registration: the Streamable HTTP transport is explicitly designed so "the server operates as an independent process that can handle multiple client connections" [S3]. Register the user-scoped server with `--transport http` against one long-lived local server (for brave: the same Docker image in `BRAVE_MCP_TRANSPORT=http` mode with `--restart unless-stopped`) and Claude Code spawns **zero** per-session processes. The trade-off is auto-start: an HTTP entry in `~/.claude.json` is just a URL, so the one-time server start moves to the install script + a Docker restart policy. > Builds on [brave-mcp-single-docker-container](../brave-mcp-single-docker-container/index.md), whose exec-wrapper (shipped as TASK-020) shares one *container* but still runs one *server process per session*.
11
+
12
+ ## Research Questions
13
+
14
+ 1. Is one-process-per-session a Claude Code implementation choice or an MCP protocol property?
15
+ 2. Does Claude Code have any mechanism (config, flag, daemon) to share a stdio server across concurrent sessions?
16
+ 3. What patterns achieve exactly one server process globally, and what does each cost?
17
+ 4. What keeps a shared server alive without manual user management?
18
+ 5. What would change relative to the just-shipped TASK-020 exec-wrapper design?
19
+
20
+ ## Current State (Codebase)
21
+
22
+ - `lib/scripts/install-mcps.sh::_add_brave` (post-TASK-020, `pending-uat`) registers brave-search at forced user scope with the `sh -c` wrapper: persistent named container `brave-search-mcp` idling on `sleep infinity`, plus `docker exec -i … node dist/index.js` per session [S1]. This yields **one container but N server processes** for N concurrent sessions — it solved the name-collision and manual-management problems, not process count.
23
+ - The prior research report documents the full option space that led there, including the HTTP option it rejected *only* because of the "must start via the command in `.claude.json`" constraint [S2].
24
+
25
+ ## Key Findings
26
+
27
+ 1. **The per-session process is protocol design.** MCP's stdio transport: "The client launches the MCP server as a subprocess" and the message loop ends with "Close stdin, terminate subprocess" — the server's lifetime *is* the client connection [S3]. A community issue states it crisply: "The MCP spec defines stdio as 1 client : 1 subprocess; there's no in-protocol multiplexing for stdio" [S6].
28
+ 2. **Each Claude Code session is an independent MCP client.** Nothing coordinates MCP processes between sessions; 4 sessions × 6 servers = 24 processes. Sharing is filed as feature request #28860 ("Shared MCP daemon: A single MCP server process per workspace that multiplexes requests") and #40220 (a "singleton/shared mode" for servers holding singleton resources) — both open enhancements, not shipped behavior [S4][S5]. So today, **no Claude Code config can make a stdio-registered server shared**.
29
+ 3. **Streamable HTTP is the sanctioned single-process path.** Per the spec, an HTTP MCP server "operates as an independent process that can handle multiple client connections", with per-client `Mcp-Session-Id` session management [S3]. Issue #63749 reaches the same conclusion: "When a server supports it, multiple clients can share one process per spec. This is the cleanest path for servers that can run as HTTP" [S6].
30
+ 4. **The brave image natively supports HTTP mode** — `BRAVE_MCP_TRANSPORT=http` (or `--transport http`), port 8080, with DNS-rebinding protections (`--allowed-origins`/`--allowed-hosts`) [S9]. One `docker run -d --restart unless-stopped` container = one server process for all sessions, surviving reboots via Docker's restart policy (given Docker Desktop starts at login).
31
+ 5. **For stdio-only servers you can still get one *server* process** via a bridge: `mcp-remote` (npm) lets stdio-only registrations connect to a remote/local HTTP server [S7], and `sparfenyuk/mcp-proxy` bridges both directions — including exposing one stdio backend over HTTP so all sessions share it [S8]. Cost: one thin proxy process per session remains (strictly "one *server* process + N proxies", not "one process").
32
+ 6. **Caveat:** a reported Claude Code bug spawned a stdio child even for HTTP-configured servers (#29688, platform:windows) — worth a `ps` check after switching; on macOS the HTTP path is the expected zero-spawn behavior [S10].
33
+
34
+ ## Constraints
35
+
36
+ - Protocol: stdio can never be shared — enforcement requires HTTP registration or a bridge; no Claude Code setting exists (or is on a roadmap with a date) for host-level sharing [S4][S6].
37
+ - An HTTP entry in `~/.claude.json` starts nothing — the "starts via the command in `.claude.json`" constraint from the prior research must be relaxed to "started once by the installer, kept alive by Docker" [S2].
38
+ - Spec security for local HTTP servers: bind localhost only; validate `Origin` [S3]. The brave server ships these controls [S9].
39
+ - TASK-020 is `pending-uat` — switching to HTTP supersedes its wrapper design; decide before running UAT-020.
40
+
41
+ ## Solution Comparison
42
+
43
+ | Option | Server processes (N sessions) | Per-session spawns | Auto-start | Enforces "one process"? | Notes |
44
+ |--------|------------------------------|--------------------|-----------|------------------------|-------|
45
+ | **A. TASK-020 exec-wrapper (shipped, pending-uat)** | N (in 1 container) | 1 exec each | ✅ via config | ❌ | Solves collisions + manual mgmt, not process count [S1] |
46
+ | **B. HTTP registration + long-lived container** (recommended) | **1** | **0** | Installer does one `docker run -d --restart unless-stopped`; Docker revives it thereafter | ✅ | Spec-sanctioned multi-client [S3]; brave supports HTTP natively [S9] |
47
+ | **C. Hybrid: stdio wrapper ensures HTTP backend, execs `mcp-remote` per session** | 1 (+N thin proxies) | 1 proxy each | ✅ via config | ◐ (one *server* process) | Keeps config auto-start; adds npx/`mcp-remote` dependency [S7][S8] |
48
+ | **D. Wait for host-level sharing in Claude Code** | 1 (hypothetical) | 0 | n/a | n/a | #28860/#40220 open, unscheduled [S4][S5] |
49
+
50
+ ## Recommendation
51
+
52
+ **Option B** if "exactly one process per user-scoped MCP" is the goal — it is the only pattern that fully enforces it, and it's what the protocol intends for shared servers. For brave-search:
53
+
54
+ ```bash
55
+ # one-time, done by the install script (not the user):
56
+ docker run -d --restart unless-stopped --name brave-search-mcp \
57
+ -e BRAVE_API_KEY -e BRAVE_MCP_TRANSPORT=http \
58
+ -p 127.0.0.1:8080:8080 docker.io/mcp/brave-search
59
+
60
+ claude mcp remove brave-search -s user 2>/dev/null
61
+ claude mcp add --scope user --transport http brave-search http://127.0.0.1:8080/mcp
62
+ ```
63
+
64
+ - Zero per-session spawns; one named container that is also the one server process; key rotation = `docker rm -f` + re-run (script can encapsulate).
65
+ - `--restart unless-stopped` + Docker Desktop login-start replaces the wrapper's `docker start` branch — no manual management after install.
66
+ - Bind to `127.0.0.1` only (spec security guidance [S3]).
67
+
68
+ **Risks & mitigations:** Docker Desktop not running at session start → server unreachable (surface: `claude mcp list` shows failed; mitigation: Docker Desktop "start at login", which the exec-wrapper equally depends on). #29688-style stdio-child bug → verify with `ps` after switching [S10]. Port 8080 collisions → make the port configurable in the script and in the registered URL.
69
+
70
+ **Alternative if constraints change:** if config-driven auto-start must be preserved exactly, Option C (wrapper + `mcp-remote`) gives one server process at the cost of thin per-session proxies; if per-session server processes are actually acceptable and only container hygiene matters, keep shipped Option A.
71
+
72
+ ## Next Steps
73
+
74
+ - This is now a genuine architecture fork (A vs. B) touching an in-flight task: `/decision-create single-process strategy for user-scoped brave MCP (HTTP registration vs stdio exec-wrapper)` — or, if B is simply chosen: `/task-update wiki/work/tasks/TASK-020-brave-search-mcp-docker.md switch to HTTP-mode container + --transport http registration per raw/research/mcp-one-process-per-user/index.md` before running UAT-020.
75
+ - `/wiki-ingest raw/research/mcp-one-process-per-user/index.md` to synthesize into the knowledge base.
@@ -0,0 +1,66 @@
1
+ ---
2
+ topic: a user scoped mcp --- if multiple sessions are active, why does it start a new mcp process for each session? can we enforce one process per user mcp globally?
3
+ slug: mcp-one-process-per-user
4
+ researched: 2026-07-28
5
+ ---
6
+
7
+ # Primary Sources — One process per user-scoped MCP
8
+
9
+ | ID | Type | Locator | Accessed | What it contributed |
10
+ |----|------|---------|----------|---------------------|
11
+ | S1 | codebase | `lib/scripts/install-mcps.sh::_add_brave` | 2026-07-28 | Shipped TASK-020 state: exec-wrapper = one container, one exec'd server process per session |
12
+ | S2 | codebase | `raw/research/brave-mcp-single-docker-container/index.md` (+ its `sources.md`) | 2026-07-28 | Prior option space; HTTP rejected there solely on the "starts via `.claude.json`" constraint; per-session spawn finding |
13
+ | S3 | web | https://modelcontextprotocol.io/specification/2025-06-18/basic/transports | 2026-07-28 | stdio: client launches server as subprocess, lifecycle bound to client; Streamable HTTP: one independent process, multiple client connections, `Mcp-Session-Id`; localhost-bind + Origin-validation guidance |
14
+ | S4 | web | https://github.com/anthropics/claude-code/issues/28860 | 2026-07-28 | Open feature request: share MCP server processes across concurrent sessions ("shared MCP daemon") — confirms no such mechanism ships today |
15
+ | S5 | web | https://github.com/anthropics/claude-code/issues/40220 | 2026-07-28 | Open request for "singleton/shared mode"; concrete failure of per-session spawning with singleton resources (Telegram 409) |
16
+ | S6 | web | https://github.com/anthropics/claude-code/issues/63749 | 2026-07-28 | "stdio = 1 client : 1 subprocess, no in-protocol multiplexing"; HTTP named the cleanest shared-process path |
17
+ | S7 | web | https://www.npmjs.com/package/mcp-remote | 2026-07-28 | Standard stdio→remote-HTTP proxy shim for stdio-only clients (Option C building block) |
18
+ | S8 | web | https://github.com/sparfenyuk/mcp-proxy | 2026-07-28 | Bidirectional stdio↔Streamable-HTTP bridge; can expose one stdio backend over HTTP for shared use |
19
+ | S9 | web | https://github.com/brave/brave-search-mcp-server | 2026-07-28 | Native HTTP transport (`BRAVE_MCP_TRANSPORT=http`, port 8080) with `--allowed-origins`/`--allowed-hosts` DNS-rebinding protections |
20
+ | S10 | web | https://github.com/anthropics/claude-code/issues/29688 | 2026-07-28 | Caveat bug: stdio child spawned even for HTTP-configured servers (Windows) — verify zero-spawn after switching |
21
+
22
+ ## Excerpts
23
+
24
+ ### S3 — MCP Specification 2025-06-18: Transports
25
+ https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
26
+ > In the **stdio** transport: The client launches the MCP server as a subprocess. The server reads JSON-RPC messages from its standard input (`stdin`) and sends messages to its standard output (`stdout`).
27
+
28
+ > Client->>Server Process: Close stdin, terminate subprocess
29
+
30
+ > In the **Streamable HTTP** transport, the server operates as an independent process that can handle multiple client connections.
31
+
32
+ > When running locally, servers **SHOULD** bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0)
33
+
34
+ ### S4 — anthropics/claude-code#28860
35
+ https://github.com/anthropics/claude-code/issues/28860
36
+ > MCP servers that are configured at the project or user level should be shared as a single process (or process group) across all concurrent Claude Code sessions in the same workspace, rather than spawning duplicate instances. For example, 4 sessions with 6 MCP servers should spawn 6 MCP processes total, not 42. Shared MCP daemon: A single MCP server process per workspace that multiplexes requests from multiple Claude Code sessions
37
+
38
+ ### S5 — anthropics/claude-code#40220
39
+ https://github.com/anthropics/claude-code/issues/40220
40
+ > When running two Claude Code sessions on the same machine, both sessions independently spawn their own MCP server processes. ... Globally configured MCP servers should either support a "singleton" / "shared" mode, where only one session owns the process and others share or skip it
41
+
42
+ ### S6 — anthropics/claude-code#63749
43
+ https://github.com/anthropics/claude-code/issues/63749
44
+ > The MCP spec defines stdio as 1 client : 1 subprocess; there's no in-protocol multiplexing for stdio.
45
+
46
+ > When a server supports it, multiple clients can share one process per spec. This is the cleanest path for servers that can run as HTTP.
47
+
48
+ ### S7 — mcp-remote (npm)
49
+ https://www.npmjs.com/package/mcp-remote
50
+ > Remote proxy for Model Context Protocol, allowing local-only clients to connect to remote servers using oAuth.
51
+
52
+ > So far, the majority of MCP servers in the wild are installed locally, using the stdio transport.
53
+
54
+ ### S8 — sparfenyuk/mcp-proxy (GitHub)
55
+ https://github.com/sparfenyuk/mcp-proxy
56
+ > The mcp-proxy is a tool that lets you switch between server transports. There are two supported modes: ... Run a proxy server from stdio that connects to a remote SSE server. ... mcp-proxy --port=8080 uvx mcp-server-fetch
57
+
58
+ ### S9 — brave/brave-search-mcp-server (GitHub)
59
+ https://github.com/brave/brave-search-mcp-server
60
+ > BRAVE_MCP_TRANSPORT: Transport mode ("http" or "stdio", default: "stdio")
61
+
62
+ > --transport <stdio|http> Transport type (default: stdio) --port <number> HTTP server port (default: 8080) ... --allowed-origins <origins...> Allowed Origin header values for HTTP transport (DNS rebinding protection)
63
+
64
+ ### S10 — anthropics/claude-code#29688
65
+ https://github.com/anthropics/claude-code/issues/29688
66
+ > When an MCP server is configured with "type": "http" in ~/.claude/claude.json, Claude Code still spawns a separate stdio child process for the same server on every new session. This results in redundant MCP server processes accumulating — one stdio process per Claude Code session, in addition to the shared HTTP server.