fix(mcp): .mcp.json project-context fallback — no 'missing CLAUDE_PLUGIN_ROOT' warning — 0.24.5#18
Merged
Merged
Conversation
…AUDE_PLUGIN_ROOT') — 0.24.5
The repo-root .mcp.json is read BOTH as the plugin's MCP manifest (plugin
context, CLAUDE_PLUGIN_ROOT set) AND as the project-scoped MCP config when the
cloned repo is opened as a project (CLAUDE_PLUGIN_ROOT unset). The bare
${CLAUDE_PLUGIN_ROOT} had no default, so the project context warned 'Missing
environment variables: CLAUDE_PLUGIN_ROOT' and the server didn't start there.
Fix: ${CLAUDE_PLUGIN_ROOT:-.} (documented ${VAR:-default} expansion). In plugin
context the var is set so the default is never evaluated -> the installed-plugin
MCP is unchanged (zero regression risk); in project context it falls back to a
repo-relative path so the warning is gone. validate-plugin.sh now fails on a bare
${CLAUDE_PLUGIN_ROOT} in .mcp.json (regression guard + 2 test cases). Confirmed
via the claude-code-guide / Claude Code MCP docs.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes a cross-context MCP config issue where the repo-root .mcp.json is interpreted both as the plugin MCP manifest and as project-scoped MCP config; in project context CLAUDE_PLUGIN_ROOT is unset, causing a “Missing environment variables: CLAUDE_PLUGIN_ROOT” warning and preventing the knowledge-base server from starting.
Changes:
- Update
.mcp.jsonto use${CLAUDE_PLUGIN_ROOT:-.}so the path resolves in both plugin and project contexts. - Add a validator guard in
scripts/validate-plugin.shto fail if.mcp.jsoncontains a bare${CLAUDE_PLUGIN_ROOT}(no default). - Add regression tests for the validator behavior and bump version metadata/docs to
0.24.5.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
tests/test-validate-plugin.sh |
Adds regression cases ensuring bare ${CLAUDE_PLUGIN_ROOT} fails validation and the :-. fallback passes. |
scripts/validate-plugin.sh |
Enforces the “no bare ${CLAUDE_PLUGIN_ROOT} in .mcp.json” rule to prevent project-context warnings. |
.mcp.json |
Switches MCP server path to ${CLAUDE_PLUGIN_ROOT:-.} to support both contexts. |
skills/upgrade/SKILL.md |
Documents the 0.24.5 migration note for the .mcp.json cross-context fix. |
.claude-plugin/plugin.json |
Bumps plugin version to 0.24.5. |
.claude-plugin/marketplace.json |
Bumps marketplace version to 0.24.5. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
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.
Symptom
Opening the cloned repo as a project (e.g. on Windows
C:\Workplace\Projects\claude-code-plugin):Root cause — ours (config), not a Claude bug
The repo-root
.mcp.jsonis read in two contexts: as the plugin's MCP manifest (plugin context —CLAUDE_PLUGIN_ROOTis set) and as the project-scoped MCP config when the repo is opened as a project (CLAUDE_PLUGIN_ROOTis not set). The path used a bare${CLAUDE_PLUGIN_ROOT}with no default, so the project context couldn't resolve it → the warning, and the server didn't start there. Claude was correctly reporting the missing var.Fix
${CLAUDE_PLUGIN_ROOT}→${CLAUDE_PLUGIN_ROOT:-.}(the documented${VAR:-default}expansion).:-default is never evaluated → the installed-plugin MCP is byte-for-byte unchanged — zero regression risk to existing installs.validate-plugin.shgains a regression guard that fails on a bare${CLAUDE_PLUGIN_ROOT}in.mcp.json(+ 2test-validate-plugin.shcases: bad form fails, fixed form passes). Verified against the Claude Code MCP docs via the claude-code-guide agent (confirmed${VAR:-default}is supported;${VAR:?error}is not).Verification
Full suite green (72 shell + 357 vitest); validator passes on the real plugin; version lockstep 0.24.5; upgrade migration row added. Config/script/test-only — no state migration.
🤖 Generated with Claude Code