fix(mcp): pre-install MCP servers globally to skip npx cache contention

[lukemarsden]

Summary

Spec-task containers were consistently failing to register chrome-devtools and github MCP servers in Zed, surfacing as 180s chrome-devtools/github context server failed to start: Context server request timeout errors and mcp__chrome-devtools__* / mcp__github__* returning Error: No such tool available from agents.

Investigation traced this to TWO compounding root causes — npm _npx/<hash> cache contention from parallel npx spawns, and Zed's agent panel speculatively spawning a "draft" Claude ACP child on every container restart that doubled the cache contention.

Full diagnosis in design/2026-05-13-mcp-cache-contention-and-duplicate-claude-spawn.md.

Root cause

When two npx <pkg> invocations target the same package against the same npm cache directory in parallel, npm's "reify mark retired" rename dance (rename node_modules/<pkg> → .<pkg>-<rand>, reinstall, rename back) races and the spawned MCP server's JSON-RPC initialize never returns. Long-running spec_tasks made this much worse because every container restart spawned an extra "draft" Claude with its own MCP children, all racing for the same cache. The user's example task spt_01kqc4ev5rt9rknk6g8dbkzj9a had accumulated 10 phantom helix_session rows (8 with zero interactions) from this pattern.

Manual reproduction with the exact protocol version, env vars and shell wrapping Zed uses returns initialize in <2s — the hang is purely in the parallel npm cache install path, not the MCP protocol or server.

Fixes (across this PR + helixml/zed PR #56)

Bottom layer: stop the npm cache race

• Dockerfile.ubuntu-helix — pin and globally install chrome-devtools-mcp@0.25.0 and @modelcontextprotocol/server-github@2025.4.8 next to the existing global drone-ci-mcp. When the binary is in PATH, npm exec <pkg> resolves it directly and skips _npx.
• api/pkg/external-agent/zed_config.go — chrome-devtools uses /usr/bin/chrome-devtools-mcp directly instead of npx chrome-devtools-mcp@latest.
• desktop/shared/helix-npx.sh + Dockerfile — /usr/local/bin/npx shim that gives each invocation its own NPM_CONFIG_CACHE so user-provided npx-based MCPs don't race either.

Frontend / sample / doc cleanup (so future projects don't reproduce the bug)

• frontend/src/components/app/GitHubMcpSkill.tsx — clicking "Enable" on the GitHub skill now writes command: 'mcp-server-github' instead of command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'].
• frontend/src/components/app/AddLocalMcpSkillDialog.tsx — the "Drone CI" example chip and command-line placeholder now use drone-ci-mcp directly.
• frontend/src/components/app/Skills.tsx — refreshed description text.
• api/pkg/server/simple_sample_projects.go — Helix-in-Helix sample's GitHub MCP uses mcp-server-github directly.
• examples/project.yaml + docs/helix-apply.md — same change in YAML/docs examples.

Top layer: stop the duplicate Claude spawn that amplified contention

Two layered fixes shipped via Zed:

• Fix 1a (helixml/zed#56, defers UserCreatedThread): the panel's draft thread no longer emits UserCreatedThread to Helix on creation. Instead defer_user_created_thread() registers it in a pending map; the existing ensure_thread_subscription NewEntry handler flushes the emit on the first user-role entry. Drafts the user never types in are never announced.
• Fix 1b (helixml/zed#56, suppresses speculative draft activation): under the external_websocket_sync cargo feature, AgentPanel::ensure_thread_initialized no longer calls activate_draft on Panel::set_active(true). Helix drives all real conversations through the chat_message WebSocket path (which goes via create_new_thread_sync, NOT activate_draft), so spec-task functionality is unaffected. E2E-verified: 1 Claude process per fresh spec-task container, down from 2.

Helix-side defensive guard (Fix 2)

• api/pkg/server/websocket_external_agent_sync.go::handleUserCreatedThread — refuses to create a new helix_session when the spec_task already has an active work_session whose helix_session has zero interactions. Belt-and-braces against old Zed binaries in long-lived containers.

Tests

• api/pkg/server/websocket_external_agent_sync_test.go — 2 new tests: TestUserCreatedThread_PhantomDraftGuard_RefusesWhenEmptyWorkSessionExists (verified to FAIL when the guard is removed — gomock surfaces "Unexpected call to CreateSession") and TestUserCreatedThread_PhantomDraftGuard_AllowsWhenExistingSessionHasInteractions (positive control).
• Zed unit tests (helixml/zed#56) — 6 tests for the defer/flush/drop API in thread_service.rs.
• E2E Phase 16 (helixml/zed#56) — asserts 0 spontaneous user_created_thread events arrive per round (catches Fix 1a regression).
• E2E Phase 17 (helixml/zed#56) — counts live claude --output-format processes via ps and asserts the count equals real threads created in the round (catches Fix 1b regression).
• E2E Phase 15 rewrite (helixml/zed#56) — the original "30% of content by midpoint" assertion false-failed for Claude Code's "thinking-then-burst" streaming pattern. Replaced with "no more than 90% of final content arrives in the LAST 20% of stream time" — agent-agnostic, catches the actual everything-arrives-at-end bug pattern, tolerates legitimate non-linear streaming.

Bumps

• sandbox-versions.txt → ZED_COMMIT=769a463a2f to pin all of the above.

Test plan

• ./stack build-ubuntu produces image with all 3 MCPs at /usr/bin/{chrome-devtools-mcp,mcp-server-github,drone-ci-mcp} + helix-npx shim at /usr/local/bin/npx.
• CGO_ENABLED=1 go test -v -run "TestWebSocketSyncSuite/TestUserCreatedThread" ./api/pkg/server/ -count=1 — all 7 UserCreatedThread tests pass.
• Verified the new phantom-draft tests FAIL when the guard is removed (regression-test power confirmed).
• cd frontend && yarn build clean.
• Started a fresh spec-task in inner-Helix with the new Zed binary:
  • Zed log shows 📌 Deferring UserCreatedThread for <draft_uuid> for the panel's draft (Fix 1a working).
  • Live process count: exactly 1 Claude alive (down from 2 — Fix 1b working).
  • DB: exactly 1 row in spec_task_zed_threads for the test task (was 2 pre-fix).
  • mcp__chrome-devtools__list_pages returned about:blank [selected], mcp__github__list_pull_requests returned PR fix(mcp): pre-install MCP servers globally to skip npx cache contention #2418 data (no MCP timeouts).
• CI (Drone build feat(kodit): index internal repos #1401) — all unit + integration tests pass.

Related

• Zed PR: fix(external_websocket_sync): defer UserCreatedThread until first user message zed#56
• Design doc: design/2026-05-13-mcp-cache-contention-and-duplicate-claude-spawn.md

Follow-ups (out of scope for this PR)

Existing user projects whose project-level MCP config was set up via the old GitHubMcpSkill.tsx (writing command: 'npx', args: ['-y', '@modelcontextprotocol/server-github']) will keep that bad config in their project DB row until the user re-saves the skill in Project Settings. New project creation uses the fixed config from this PR.

🤖 Generated with Claude Code