Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Claude plugin .mcp.json declarations are ignored at runtime

Open Beginner friendly
#148 1 comment 0 reactions 0 assignees View on GitHub

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
Domain
backend, cli, tooling

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

untriaged
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
  1. Create a Claude-style plugin with .claude-plugin/plugin.json.
  2. Add a root .mcp.json containing a stdio MCP server, for example a tiny Node process that writes a marker file when it starts.
  3. Add the plugin through a local marketplace and install it with /plugin install.
  4. Restart Step.
  5. The plugin is still listed as installed, but the marker from the .mcp.json server 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from stepfun-ai/Step-Code

All issues in stepfun-ai/Step-Code

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.