Skip to content

fix: wrap .mcp.json contents in mcpServers key (fixes #1) - #2

Merged
sugi-chan merged 3 commits into
mainfrom
fix/mcp-json-wrapper
Apr 20, 2026
Merged

sugi-chan merged 3 commits into
mainfrom
fix/mcp-json-wrapper

Conversation

@sugi-chan

@sugi-chan sugi-chan commented Apr 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The repo's .mcp.json was missing the mcpServers wrapper key that Claude Code requires. Without it, the plugin system parses the file but finds no servers to register, so mcp__speed-run__* tools never become available.

The Bug

Before:
```json
{
"speed-run": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"],
"env": { "CEREBRAS_API_KEY": "${CEREBRAS_API_KEY}" }
}
}
```

After:
```json
{
"mcpServers": {
"speed-run": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"],
"env": { "CEREBRAS_API_KEY": "${CEREBRAS_API_KEY}" }
}
}
}
```

Why This Fixes #1

The CLAUDE.md promises auto-registration via `.mcp.json` on plugin install. But because the committed file had the wrong structure, the registration silently did nothing. Users saw "Failed to reconnect to speed-run" because no server was ever actually registered.

The issue reporter (@nicwn) correctly created their own `.mcp.json` with the right structure in their project, but the plugin should just work out of the box.

Test plan

  • Install the plugin fresh
  • Verify `mcp__speed-run__*` tools appear without manual `.mcp.json` creation
  • Run a speed-run command and confirm Cerebras API calls work

Fixes #1

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Chores
    • Reorganized server configuration: top-level server entries are now nested under a new "mcpServers" grouping (existing server settings preserved).
    • Bumped plugin manifest version to 1.1.1.
    • Added ignore rules to exclude node modules and log files from version control.
    • Updated package metadata and developer scripts: switched build/watch tooling to esbuild, added a separate type-check script, and included esbuild as a dev dependency.

Claude Code's .mcp.json format requires servers to be nested under an
mcpServers key. Without it, the plugin system parses the file but finds
no servers to register, so mcp__speed-run__* tools never become available.

This was the root cause of issue #1 — users installing the plugin saw
"Failed to reconnect to speed-run" because auto-registration silently
did nothing.

Fixes #1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Apr 20, 2026 •

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cf67b085-2d64-43fc-9051-96b12afefbea

📥 Commits

Reviewing files that changed from the base of the PR and between a7f4ae9 and c89a0c3.

⛔ Files ignored due to path filters (5)
  • mcp/dist/cerebras-client.d.ts is excluded by !**/dist/**
  • mcp/dist/cerebras-client.js is excluded by !**/dist/**
  • mcp/dist/index.d.ts is excluded by !**/dist/**
  • mcp/dist/index.js is excluded by !**/dist/**
  • mcp/package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (2)
  • mcp/.gitignore
  • mcp/package.json
✅ Files skipped from review due to trivial changes (2)
  • mcp/.gitignore
  • mcp/package.json

Walkthrough

Top-level .mcp.json structure changed: "speed-run" is now nested under a new "mcpServers" property. Plugin manifest version bumped to 1.1.1. The mcp package metadata and build scripts were updated and a gitignore was added in the mcp/ folder.

Changes

Cohort / File(s) Summary
MCP configuration
\.mcp.json
Restructured JSON: top-level "speed-run" moved under new top-level "mcpServers" key; server command, args, and env content unchanged aside from nesting.
Plugin manifest
\.claude-plugin/plugin.json
Plugin version incremented from 1.1.0 → 1.1.1; no other manifest fields changed.
MCP package metadata & build
mcp/package.json
Package version bumped 1.0.0 → 1.1.1; build tooling switched from tsc to esbuild (build/dev scripts updated); added typecheck script and esbuild devDependency.
MCP ignore rules
mcp/\.gitignore
Added ignore rules to exclude node_modules/ and *.log files.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through JSON trees today,
Nesting one key to find the way.
Version gave a friendly spring—
Build tools hum, the servers sing. ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'fix: wrap .mcp.json contents in mcpServers key (fixes #1)' accurately and clearly describes the main change—restructuring the .mcp.json to wrap contents in the required 'mcpServers' key.
Linked Issues check ✅ Passed All code changes address the root cause from issue #1: the .mcp.json now includes the required 'mcpServers' wrapper [#1], the build system bundles dependencies via esbuild [#1], and version is incremented [#1].
Out of Scope Changes check ✅ Passed All changes are directly scoped to fixing #1: restructuring .mcp.json, switching build to esbuild for bundling, adding .gitignore, and version bumps are all necessary to resolve the MCP server registration failure.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/mcp-json-wrapper

Comment @coderabbitai help to get the list of available commands and usage tips.

The plugin ships dist/index.js but not node_modules. Without an install
hook to run npm install, Node can't resolve @modelcontextprotocol/sdk
imports at runtime and the MCP server fails to start silently — shown
as "✘ failed" in /mcp.

This was the actual cause of issue #1 (not the .mcp.json wrapper).
Users would install the plugin, the MCP would fail to start because
deps weren't installed, and they'd see "Failed to reconnect."

Switch the build from tsc to esbuild bundling:
- esbuild bundles all runtime deps into a single dist/index.js
- No node_modules needed at runtime
- Plugin "just works" on install, no hooks needed
- tsc kept as `npm run typecheck` for type validation
- Bundle verified: runs standalone in /tmp without node_modules present

Cleaned up stale .d.ts / per-file .js output from the old tsc build.
Added .gitignore for mcp/node_modules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@sugi-chan
sugi-chan merged commit 3baa3d9 into main Apr 20, 2026
1 check passed
nicwn pushed a commit to nicwn/2389-claude-plugins that referenced this pull request Apr 28, 2026
Reflects the .mcp.json wrapper fix in 2389-research/speed-run#2.
The marketplace was still pinned to 1.0.0 while the standalone repo
advanced to 1.1.0 (+ 1.1.1 for the fix).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

mcp__speed-run__* tools aren't available in this session because the MCP server wasn't registered

1 participant