crux doctor / mcp status: no runtime health check (MCP handshake probe)

[kaushalpaneri]

Feature Request

Description

crux doctor checks that MCP source directories exist and build artifacts are present, but never verifies that the MCP server actually starts and responds to a protocol handshake. This means crux doctor reports ✅ for servers that crash at runtime.

Problem

Three failures I encountered that crux doctor missed:

1. borgius/jobspy-mcp-server — Directory exists ✅, but crashes on startup with TypeError: Cannot read properties of null (reading '_zod') due to MCP SDK version incompatibility.

2. postgres-mcp (crystaldba) — Registered ✅, but pglast C extension fails to compile on Python 3.14. Server never starts.

3. @modelcontextprotocol/server-postgres — Starts and handshakes ✅, but is read-only. Agents can't INSERT/UPDATE data, which only surfaces when an agent tries to write.

Proposed Solution

Add a runtime probe to crux doctor or a new crux mcp test <name> command that:

1. Starts the MCP server (with timeout)
2. Sends initialize handshake — verifies the server responds with valid MCP protocol
3. Sends tools/list — shows available tools so the user can verify capabilities
4. Reports result: pass/fail with error details

Example output:

crux mcp test postgres
  ✅ Server starts (postgres-advanced v0.1.0)
  ✅ Handshake OK (protocol 2024-11-05)
  📋 Tools: execute_query, execute_dml_ddl_dcl_tcl, list_tables, describe_table, ...
  ⏱  Probe completed in 2.3s

crux mcp test jobspy
  ❌ Server crashed on startup
  Error: TypeError: Cannot read properties of null (reading '_zod')
  Fix: Check MCP SDK version compatibility

Impact

Without runtime probing, users discover broken MCPs only when agents fail mid-task. During my setup session, I had to manually test each MCP by piping JSON-RPC messages via stdin, which is error-prone and time-consuming.

Environment

• crux-cli version: latest
• macOS (Apple Silicon)