fix(onboarding): address Claude Code MCP onboarding friction (#2934) - #2935
Merged
Conversation
Ryan's bug report (#2934) walked through ~45 min of debugging a stock external-runtime install. This PR fixes the four items he flagged that have a small surface, and stubs out the larger ones for follow-up. Fixed in this PR ================ #1 — Python floor disclosure (README in publish bundle) Add an explicit "Requires Python ≥3.11" section that calls out the cryptic "Could not find a version that satisfies the requirement" failure mode; recommend `pipx install` over `pip install` so the binary lands on PATH automatically; show the explicit `pip install --user` alternative with the PATH caveat. #3 — MOLECULE_WORKSPACE_TOKEN_FILE support (mcp_workspace_resolver.py) Add a third resolution step between the inline env var and the in-container CONFIGS_DIR fallback. Operators can write the bearer to a 0600 file (e.g. ~/.config/molecule/token) and point MOLECULE_WORKSPACE_TOKEN_FILE at it, keeping the secret out of ~/.zsh_history and out of plaintext in MCP-host configs like ~/.claude.json. Inline TOKEN still wins on conflict so rotation flows are predictable. README documents the safer option as the recommended path. 6 new tests pin every leg (file resolves, inline wins, missing/empty file falls through, blank env unset-equivalent, help text advertises it). #4 — Push delivery 3-condition gating (README in publish bundle) Document that real-time push on Claude Code requires (a) the server to declare experimental.claude/channel (we do), (b) the server to be marketplace-plugin-sourced (operators must scaffold their own until the official marketplace lands — see #2934 follow-up), and (c) the --dangerously-load-development-channels flag on the claude invocation. Until any of the three is in place, delivery silently falls back to poll mode with no diagnostic. The README now says all of this explicitly so a new operator doesn't grep the binary for channel_enable to figure it out. #8 — serverInfo.name mismatch (a2a_mcp_server.py) The server reported `serverInfo.name = "a2a-delegation"` while operators register it as `molecule` (the name in `claude mcp add molecule …`). Harmless on tool routing today but matters for any future Claude Code allowlist that gates push by hardcoded server name. Renamed to "molecule" with an inline comment explaining the invariant. Deferred (separate issues to track) =================================== #2 — covered transitively by #1's pipx recommendation; no separate fix. #5 — `moleculesai/claude-code-plugin` marketplace repo (substantial new repo work; the README references it as a documented follow-up). #6 — `molecule-mcp doctor` subcommand (substantial new CLI surface; mentioned in the README's push-vs-poll section as the planned diagnostic for silent push fallback). #7 — `--dangerously-load-development-channels` rename — not in our control; that's Claude Code's flag. Tests ===== 164/164 mcp_cli + a2a_mcp_server tests pass locally (WORKSPACE_ID=00000000-0000-0000-0000-000000000001 pytest …) including 6 new TestTokenFileEnv cases. Wheel builds successfully via scripts/build_runtime_package.py with the new README markers verified in the output. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
HongmingWang-Rabbit
requested a review
from hongmingwang-moleculeai
as a code owner
May 5, 2026 21:19
HongmingWang-Rabbit
enabled auto-merge
May 5, 2026 21:19
This was referenced May 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2934 (partial — items #1, #3, #4, #8). Items #5 (marketplace repo) and #6 (
molecule-mcp doctor) are larger efforts deferred to follow-up issues; item #7 (--dangerouslyflag rename) is not in our control.What Ryan reported
A stock external-runtime install on macOS Python 3.9 took ~45 min to debug. Concrete pain points:
molecule-mcpnot on PATH after user-sitepip install~/.zsh_historyand~/.claude.jsonplaintextserverInfo.namereportsa2a-delegationwhile users register the server asmoleculeWhat this PR does
pipx installoverpip installMOLECULE_WORKSPACE_TOKEN_FILEenv var lets operators point at a 0600 file. Resolution order: inline env > file >${CONFIGS_DIR}/.auth_token. 6 new tests.serverInfo.namea2a-delegation→moleculeto match how operators register itFiles
scripts/build_runtime_package.py— README template (the README that ships in the wheel + mirror repo + PyPI page)workspace/mcp_workspace_resolver.py—_read_token_from_file_env()+ updated help text + docstringworkspace/a2a_mcp_server.py—serverInfo.nameworkspace/tests/test_mcp_cli_split.py—TestTokenFileEnvclass with 6 casesWhat this doesn't fix (deferred)
moleculesai/claude-code-pluginis a brand-new public repo that needs scaffolding, marketplace.json schema decisions, plugin.json generation from the wheel, and CI to keep them in lockstep. Separate issue worth its own design pass.molecule-mcp doctorsubcommand — substantial new CLI surface (Python ver check, wheel location, PATH check, heartbeat probe, per-MCP-entry diagnostics). The README now references this as the planned diagnostic so operators know the gap is acknowledged.--dangerously…rename — Claude Code's flag, not ours.molecule-mcp install-claude-codesubcommand — partially mitigated by the pipx recommendation in chore: rebrand icons + LICENSE cleanup + HANDOFF.md #1 (binary lands on PATH automatically); aclaude mcp addwrapper is adoctor-adjacent follow-up.Test plan
test_mcp_cli*.py+test_a2a_mcp_server.pypass locally withWORKSPACE_ID=…setTestTokenFileEnvcases pin every leg of the new resolver pathscripts/build_runtime_package.py --version 0.99.99-dev …) succeeds and the built README contains all expected markers🤖 Generated with Claude Code