mcp start: console.log in ONNX loader corrupts stdout JSON-RPC → 'Failed to connect' in Claude Code

[markt-heximal]

Summary

npx ruvector mcp start fails the MCP handshake in Claude Code (claude mcp list → ✘ Failed to connect) because a console.log writes to stdout, which is the JSON-RPC channel for the MCP stdio transport. One stray line corrupts the initialize handshake.

Version

ruvector 0.2.35 (server reports "2.0")

Root cause

dist/core/onnx/loader.js:199 (source likely src/core/onnx/loader.ts) logs on a disk-cache hit:

console.log(`  Disk cache hit: ${modelName}`);

console.log → stdout. Under the MCP stdio transport, stdout must contain only JSON-RPC frames, so this line makes the client's first read non-JSON and the handshake fails.

Evidence

Driving a real MCP initialize over stdin with the streams separated:

• stdout (must be pure JSON-RPC): Disk cache hit: all-MiniLM-L6-v2 ← the pollution
• stderr (correct): ParallelIntelligence: N workers ready, Loading ONNX model: all-MiniLM-L6-v2..., ONNX embedder ready: 384d, SIMD: true

So the embedder's other logs are already on stderr — only this cache-hit line leaks to stdout. It appears only once the model is disk-cached (steady state), which makes the failure look intermittent.

ruvector mcp test passes (97 tools registered) and the server is otherwise healthy — the problem is purely stdout hygiene on the stdio transport.

Fix

Send it to stderr, consistent with the rest of the embedder logs (and with ruv-swarm's stdio server — "logs to stderr, not stdout … Critical" — and RuView's "Logs go to stderr ONLY — stdout is the JSON-RPC channel and must stay clean"):

console.error(`  Disk cache hit: ${modelName}`);

Or gate loader logging behind a debug flag when running under mcp start.

Impact

ruvector mcp start cannot connect to any stdio MCP host (Claude Code, Inspector) whenever the ONNX model is disk-cached — which is the normal steady state.

[stuinfla]

Confirming this independently against the published ruvector@0.2.35 tarball — dist/core/onnx/loader.js:199 is exactly as you describe, and your stdout/stderr separation is the right diagnosis.

Two findings from verifying it that I think change the fix:

1. There are five of these, not one. All on the same module, all corrupting a stdio frame identically:

loader.js:153   console.log(`Loading model: ${modelConfig.name} (${modelConfig.size})`)
loader.js:199   console.log(`  Disk cache hit: ${modelName}`)        ← this issue
loader.js:277   console.log(`  Cache hit: ${cacheKey}`)
loader.js:288   console.log(`  Downloading: ${url}`)
loader.js:368   console.log('Model cache cleared')

This explains the intermittency you noted. Line 199 fires on a warm disk cache; a cold cache reaches Downloading: and Loading model: first. So patching only 199 moves the failure from the steady state to the first run rather than eliminating it. All five want console.error.

2. Fixing this issue alone will not make mcp start connect. There's a second, unrelated wall behind it: bin/mcp-server.js:4087 gates its bootstrap on require.main === module, while bin/cli.js:8147 loads it via require(mcpServerPath) — so the guard is structurally always false, main() never runs, and server.connect(transport) is never called. The process registers its handlers and silently listens to nothing.

Filed separately as #715, since the root cause is unrelated to stdout hygiene.

Flagging it here because of the verification trap: if someone patches line 199, retests with Claude Code, and still sees ✘ Failed to connect, the natural conclusion is that this diagnosis was wrong. It isn't — both bugs have to be fixed before the handshake completes. Confirmed that with both patches applied, initialize returns a proper JSON-RPC result.

Credit for the second bug goes to Agentist-Elder, who found it downstream at stuinfla/ruvnet-brain#37.