fix: Send all logs to stderr for stdio transport compatibility

facundofarias · claude · facundofarias · commit 335e59908b19 · 2025-11-11T07:42:39.000+01:00
The stdio transport requires stdout to be reserved exclusively for JSON-RPC messages. Logging to stdout causes "Unexpected token" errors in Claude Desktop. Changes: - Update logger.ts to use console.error for all log levels (info, error, debug) - Add comment explaining stdio transport requirement - Document the issue and solution in STDIO_MIGRATION.md Troubleshooting section This fixes the "Unexpected token 'I', "[INFO] 2025"... is not valid JSON" error. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/STDIO_MIGRATION.md b/STDIO_MIGRATION.md
@@ -36,14 +36,19 @@ This document describes the changes made to convert the DeployHQ MCP server from
 - Updated architecture diagram to show stdio transport
 - Updated security section to emphasize local credential management
 
+#### `src/utils/logger.ts`
+- **CRITICAL FIX**: Changed all logging to use `console.error` instead of `console.log`
+- stdio transport requires stdout to be reserved exclusively for JSON-RPC messages
+- Logging to stdout causes "Unexpected token" errors in Claude Desktop
+- All logs (info, error, debug) now properly go to stderr
+
 ### 3. Unchanged Files (for hosted deployment)
 
 - `src/index.ts` - Express server entrypoint
 - `src/mcp-server.ts` - Core MCP server factory (shared by both transports)
 - `src/tools.ts` - Tool definitions (shared)
 - `src/api-client.ts` - DeployHQ API client (shared)
 - `src/transports/` - SSE and HTTP transport handlers
-- `src/utils/` - Logger and utilities
 
 ## Usage
 
@@ -144,6 +149,29 @@ After (stdio):
 5. **No Infrastructure**: No hosting costs or maintenance
 6. **Backwards Compatible**: Hosted version still available if needed
 
+## Troubleshooting
+
+### "Unexpected token" JSON errors in Claude Desktop
+
+**Problem**: Claude Desktop shows errors like:
+```
+Unexpected token 'I', "[INFO] 2025"... is not valid JSON
+```
+
+**Cause**: The stdio transport uses stdout exclusively for JSON-RPC messages. Any other output (logs, debug messages, etc.) to stdout will corrupt the JSON stream.
+
+**Solution**: All logging must use `console.error` (stderr) instead of `console.log` (stdout).
+
+```typescript
+// &#10060; Wrong - writes to stdout, breaks stdio
+console.log('[INFO] Starting server...');
+
+// &#9989; Correct - writes to stderr, preserves stdio
+console.error('[INFO] Starting server...');
+```
+
+This is why our logger uses `console.error` for all log levels.
+
 ## Next Steps
 
 To publish to npm:
diff --git a/src/utils/logger.ts b/src/utils/logger.ts
@@ -1,17 +1,19 @@
 /**
  * Shared logger utility
+ * IMPORTANT: For stdio transport, all logs must go to stderr (not stdout)
+ * stdout is reserved exclusively for JSON-RPC messages
  */
 
 export const log = {
   info: (message: string, ...args: unknown[]): void => {
-    console.log(`[INFO] ${new Date().toISOString()} - ${message}`, ...args);
+    console.error(`[INFO] ${new Date().toISOString()} - ${message}`, ...args);
   },
   error: (message: string, ...args: unknown[]): void => {
     console.error(`[ERROR] ${new Date().toISOString()} - ${message}`, ...args);
   },
   debug: (message: string, ...args: unknown[]): void => {
     if (process.env.NODE_ENV === 'development' || process.env.LOG_LEVEL === 'debug') {
-      console.log(`[DEBUG] ${new Date().toISOString()} - ${message}`, ...args);
+      console.error(`[DEBUG] ${new Date().toISOString()} - ${message}`, ...args);
     }
   },
 };
