Claude plugin .mcp.json declarations are ignored at runtime
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 70/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- node.js, typescript
Research direction
The issue is in the runtime discovery function discoverStepMcpServers(). Look at the plugin loader code that normalizes .mcp.json to a string declaration. The fix involves modifying the discovery logic to handle string declarations (file paths) and parse the referenced .mcp.json file. Check the existing tests for plugin diagnostics and runtime discovery to understand the expected behavior and add a regression test.
Written by the indexing model from the issue text.
Description
What happened?
Claude-style plugins with a root .mcp.json are recognized and installed by Step, but their MCP servers are not discovered after restart.
The plugin loader normalizes a Claude plugin with .mcp.json to mcpServers: ".mcp.json", and the diagnostics path accepts that file-backed declaration. The runtime path in discoverStepMcpServers() currently skips string declarations entirely:
if (!declared || typeof declared === "string") continue;
So the plugin appears under /plugin as installed, but its MCP server never starts. An otherwise equivalent plugin with inline mcpServers starts normally.
Steps to reproduce
- Create a Claude-style plugin with
.claude-plugin/plugin.json. - Add a root
.mcp.jsoncontaining a stdio MCP server, for example a tiny Node process that writes a marker file when it starts. - Add the plugin through a local marketplace and install it with
/plugin install. - Restart Step.
- The plugin is still listed as installed, but the marker from the
.mcp.jsonserver is never created.
As a control, moving the same server declaration inline into plugin.json -> mcpServers creates the marker after the same restart.
I have a local fix that resolves inline and file-backed declarations through one parser and added regression coverage for runtime discovery and plugin diagnostics. The focused tests pass, pnpm run check passes, and pnpm run build:offline passes. Happy to submit the fix if this direction looks good.
Expected behavior
A Claude-style plugin's root .mcp.json should be discovered and started after restart the same way as inline mcpServers.
Version
StepCode 0.1.0, main @ cb5fc1456d49d49c62e072bfed2926220083214e
AI-assisted wording; the repro, code path, fix, and tests were verified locally.
- Dominant language
- TypeScript
- Stars
- 54
- Forks
- 20
- Avg merge
- 23m
- Merged PRs (30d)
- 7
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from stepfun-ai/Step-Code
-
untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
stepfun-ai/Step-Code#153 · 2 comments ·
-
untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
stepfun-ai/Step-Code#151 · 1 comment ·
-
untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
stepfun-ai/Step-Code#149 · 1 comment ·
-
untriaged
Difficulty 1/5 Under an hour Newbie friendliness 90/100
stepfun-ai/Step-Code#144 · 1 comment ·
-
untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
stepfun-ai/Step-Code#141 · 1 comment ·
All issues in stepfun-ai/Step-Code
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
bug v2
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
modelcontextprotocol/inspector#2458 · 1 comment ·
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
railmapgen/rmp-gallery#4068 ·
-
Mend: dependency security vulnerability status: needs triage 🕵️♀️
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
carbon-design-system/ibm-products#9907 ·