Skip to content

fix(cli): gate mcp-dev-wrapper debug stderr behind env flag#38

Open
smorchj wants to merge 1 commit intonitrocloudofficial:mainfrom
smorchj:dx/gate-mcp-dev-wrapper-debug
Open

fix(cli): gate mcp-dev-wrapper debug stderr behind env flag#38
smorchj wants to merge 1 commit intonitrocloudofficial:mainfrom
smorchj:dx/gate-mcp-dev-wrapper-debug

Conversation

@smorchj
Copy link
Copy Markdown

@smorchj smorchj commented Apr 15, 2026

Closes #15

Summary

mcp-dev-wrapper currently writes hot-reload notices, the SSE log-server banner, and per-restart messages to stderr unconditionally. That's noisy when debugging stdio MCP, where stderr is the only signal channel you actually want to read.

This PR gates all informational logs behind an env flag while keeping real failures unconditional.

Changes

Single file: typescript/packages/cli/src/mcp-dev-wrapper.ts

  1. Add a DEBUG_ENABLED constant computed once at module load:
const DEBUG_ENABLED = !!(
  process.env.NITROSTACK_DEBUG ||
  /(^|,)nitrostack(:|,|$)/.test(process.env.DEBUG ?? '')
);

Both forms are supported so users coming from the broader Node ecosystem can use the standard DEBUG=nitrostack pattern, while NITROSTACK_DEBUG=1 is the canonical short form.

  1. Add a debug(...args) helper that routes through console.error only when the flag is set.

  2. Replace 10 informational console.error calls with debug():

    • Log streaming server running at ... banner
    • MCP_SERVER_PORT is ... debug line
    • Server exited with code N (attempt N/M), restarting... (non-fatal restart)
    • Server exited with code N, restarting... (clean exit)
    • Changes detected, restarting server...
    • Server restarted successfully
    • File changed: ...
    • File added: ...
    • Shutting down...
  3. Keep these on unconditional console.error:

    • Usage line when distPath is missing
    • Server failed N times in a row. Giving up. (consecutive-failure bail-out)
    • Server error: ... from mcpProcess.on('error')
    • Unhandled rejection in run().catch()

Testing

  • npm run build passes with no TypeScript errors
  • Verified the compiled output: 6 unconditional console.error calls remain (real failures), 10 calls now route through debug()
  • With NITROSTACK_DEBUG=1 set, behavior is identical to before
  • With the flag unset, stderr only carries actual failures

Acceptance criteria

  • Debug lines (e.g. MCP_SERVER_PORT) behind NITROSTACK_DEBUG or DEBUG namespace
  • Real failures remain obvious on stderr

Closes nitrocloudofficial#15

Hot-reload notices, the SSE log-server banner, and the per-restart messages
are useful when debugging the wrapper itself but pollute stderr during
normal stdio MCP development.

Add a DEBUG_ENABLED constant gated on either:
  NITROSTACK_DEBUG=1
  DEBUG=nitrostack            (or any value containing 'nitrostack')

A new debug() helper routes informational lines through console.error only
when the flag is set. Real failures (spawn errors, the consecutive-failure
bail-out, unhandled rejections, the usage line, server.on('error')) still
go to stderr unconditionally.

Verified the build output: 6 unconditional console.error calls remain
(real failures), 10 calls now route through debug().
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.

[CLI] Gate mcp-dev-wrapper DEBUG / noisy stderr behind env flag

1 participant