Fix stdout/stderr handling to prevent JSON-RPC communication errors

[raihaku]

Title

Fix stdout/stderr handling to prevent JSON-RPC communication errors

Description

I encountered an issue when using godot-mcp with Claude Client and Amazon Q Developer CLI in MacOS15 where the MCP server would fail to establish proper communication. After investigating, I found that debug messages were being output to stdout, which interfered with the JSON-RPC protocol.

Problem

The MCP protocol requires that stdout be used exclusively for JSON-RPC messages, but godot-mcp was outputting debug information and warnings to stdout using console.debug() and console.warn(). This caused Claude's MCP client to attempt to parse these debug messages as JSON, resulting in errors like:

Unexpected token 'D', "[DEBUG] Ope"... is not valid JSON

Solution

I modified the code to redirect all debug and warning messages to stderr instead of stdout:

1. Changed the logDebug() function to use console.error() instead of console.debug()
2. Replaced all instances of console.warn() with console.error()
3. Replaced console.log() with console.error() for server status messages

This ensures that stdout is used exclusively for JSON-RPC communication, while all logging and debugging information goes to stderr.

Suggested Implementation

Here's an example of the changes I made:

// Before
private logDebug(message: string): void {
 if (DEBUG_MODE) {
   console.debug([DEBUG] ${message});
 }
}

// After
private logDebug(message: string): void {
 if (DEBUG_MODE) {
   console.error([DEBUG] ${message});
 }
}

Similar changes should be made for all console output that isn't part of the JSON-RPC protocol.

Additional Context

This issue affects any MCP client that strictly follows the protocol specification, which requires stdout to contain only valid JSON-RPC messages. By properly separating stdout and stderr usage, godot-mcp will be more compatible with all MCP clients.

[davos555]

Getting what I assume is the same issue in Cursor on Windows:

"2025-11-23 18:08:59.373 [error] Client error for command Unexpected token 'D', "[DEBUG] [Go"... is not valid JSON"