fix(plugin): move the MCP manifest off the path Claude Code auto-discovers as project scope

[kevintseng]

Summary

The repo shipped .mcp.json at its root. That one path is two things at once: the plugin loader's default MCP manifest, where ${CLAUDE_PLUGIN_ROOT} resolves, and the path Claude Code auto-discovers as a project config for anyone who merely opens this repository, where it does not. Claude Code says so itself — from the repo root, throwaway config dir, no plugin installed:

$ claude mcp list
memesh: node ${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js - ⏸ Pending approval
[Warning] [memesh] mcpServers.memesh: Missing environment variables: CLAUDE_PLUGIN_ROOT

The server then dies with -32000 Connection closed. git log -p -- .mcp.json dates the placeholder to 310ce585 on 2026-05-13, replacing a working npx -y -p @pcircle/memesh memesh-mcp. Three and a half months.

The manifest moves to .claude-plugin/mcp.json, declared by .claude-plugin/plugin.json. Three candidate shapes were installed into throwaway config dirs and all three registered; this one keeps a file, which mcpEntry(), both packed smokes and doctor already read, and it mirrors the Codex side. ${CLAUDE_PLUGIN_ROOT} stays — it is the documented, correct form inside a plugin manifest; the path was wrong, not the variable. Custom component paths supplement the defaults rather than replacing them (plugin-structure/SKILL.md:98), so declaring the new path is only half the fix: the root file has to be gone, or both still load.

Second defect — the reason the first survived. inspectMcpConfig resolved the entry with an unconditional entry.replaceAll('${CLAUDE_PLUGIN_ROOT}', packageRoot), so the referenced file always existed and the check could never fail. A green light was guarding exactly this. It now substitutes only where something really does substitute (plugin-marketplace, or a real CLAUDE_PLUGIN_ROOT in the environment) and otherwise reports the entry as NOT VERIFIED with the command that would verify it — as a warn, not the existing informational "NOT VERIFIED" idiom, because summarizeOverallStatus filters informational rows out and a row that cannot move a verdict is the same shape as the defect being fixed. Consequence reviewers should expect: every source-checkout memesh doctor now reports PASS_WITH_CONCERNS; CI accepts it (the CLI exits non-zero only on FAIL).

The suite was holding the defect in place. tests/installation.test.ts asserted .mcp.json exists; tests/release-preconditions.test.ts and scripts/check-agent-message-sync.mjs required it in their path lists. All three now require its absence and the new declaration instead.

Type of change

• Bug fix (fix) — install path
• Docs (docs)

Docs synced

• CHANGELOG.md, docs/api/API_REFERENCE.md, docs/platforms/README.md, .github/CODEOWNERS, .gitignore
• 22 new i18n entries (summary + fix × 11 locales), enforced by tests/dashboard-i18n.test.ts
• dist/ and dashboard/dist/ regenerated

Verification

• The install, end to end — local marketplace, throwaway CLAUDE_CONFIG_DIR: claude plugin install memesh@pcircle-memesh → claude mcp list → plugin:memesh:memesh: node …/dist/mcp/server.js - ✔ Connected. That is a completed MCP handshake, not just registration.
• The opposite direction, re-run by the orchestrator: repo root, fresh config dir, CLAUDE_PLUGIN_ROOT unset → No MCP servers configured. and ls .mcp.json → no such file.
• Break-test A: reintroduce the root .mcp.json → 3 tests red and check-agent-message-sync: FAIL. Removed → 36/36, PASS.
• Break-test B: restore the unconditional substitution → Tests 2 failed | 150 passed, including "resolves against CLAUDE_PLUGIN_ROOT when the environment actually provides one" — a pass it had not earned. Restored → 152/152.
• Whole suite exit 0 (230 files / 3278 tests); lint 0, typecheck 0, check-doc-claims 0, check-codemap-parity 0, test:packaged 0, test:packaged:upgrade 0, verify:release 0.
• Evidence Gates: eg check PASS at base 2d4c0f04 — mcp-manifest-not-project-scoped CODE_COMPLETE and doctor-mcp-check-can-fail INTEGRATION_VERIFIED (ui_route: the dashboard bundle carries the new strings), 9 receipts including two known_bad_mutation failure paths.

Not proven

• claude plugin details <name> reports MCP servers (0) for every manifest shape, including the inline one — details under-reports; claude mcp list is authoritative. Worth knowing before anyone verifies this with the wrong command.
• The ✔ Connected handshake ran against this worktree's dist/ via a local marketplace, not a published npm tarball. The packed-artifact smoke covers the tarball's contents; no end-to-end install from the real marketplace was performed.
• The 10 non-English i18n strings are adapted from each locale's existing mcp-config.* sentences; no native reviewer checked them.

Found while verifying this, not fixed here

scripts/smoke-packed-artifact.mjs spreads ...process.env in six places without stripping MEMESH_DIR/MEMESH_DB_PATH, so a maintainer who has them set gets a failing smoke: env -u MEMESH_DIR npm run test:packaged → exit 0, MEMESH_DIR=… npm run test:packaged → exit 1 (ENOENT … /mr-XXXX/.memesh/router.token). Same defect class as #271, in the sibling script that PR #280 did not touch. Filed separately.