MCP stdio handshake fails because server writes non-JSON logs to stdout before initialize response

[sserdyuk]

Summary

tailwindcss-mcp-server prints startup logs to stdout before sending JSON-RPC frames.
MCP clients that require clean stdio JSON-RPC fail startup with errors like:

MCP startup failed: handshaking with MCP server failed: connection closed: initialize response

Impact

Codex/other MCP clients fail to start this server reliably.

Repro

1. Install and run:

   npm i tailwindcss-mcp-server@0.1.1
   printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}'| node node_modules/tailwindcss-mcp-server/build/index.js

2. Observe stdout contains non-JSON lines before initialize result:

   • DocumentationScraperService initialized
   • UtilityMapperService initialized
   • then JSON initialize response

Expected

For stdio MCP transport, stdout should contain only JSON-RPC messages.
All logs should go to stderr (or be disabled).

Actual

Non-protocol text is written to stdout, corrupting protocol framing.

Suggested fix

• Move all diagnostic logs from console.log to console.error (or gated debug logger to stderr).
• Ensure stdout emits only JSON-RPC frames.