fix(server): keep the "MCP error <code>:" prefix off tool result envelopes (#647)

[debugmcpdev]

Summary

Every tool that hit a session-lifecycle failure (session not found / terminated / no active proxy) returned {"success": false, "error": "MCP error -32600: Cannot step over: no active proxy for session …"} — the typed session errors extend the SDK's McpError, whose constructor bakes the JSON-RPC code into .message, and sessionErrorToResult copied that verbatim.

• src/errors/debug-errors.ts — new DebugError base (extends McpError) that records the plain text as detail; every typed error moves onto it. .message is untouched, so the JSON-RPC path (dispatch rethrows McpError; the SDK derives the wire error from the code) still carries the prefix. getErrorMessage() reports detail for a DebugError.
• src/server/tool-result.ts — sessionErrorToResult puts error.detail in the envelope. This is the single choke point every handler family goes through, so no handler changes.
• Rider: list_threads' failure now reads Cannot list threads: … (was Cannot listThreads: …).
• Tests: tool-result.test.ts pins the un-prefixed envelope; new tests/core/unit/errors/debug-errors.test.ts covers every class (.message prefixed, .detail plain, .data structured, getErrorMessage).
• Docs: the step_over/into/out report success:false with the message "Stepped over", dropping the actual reason #638 case study, which quotes the prefixed envelope, notes the fix. Changelog fragment changelog.d/647.fixed.md.

Verified live (mcp-debugger on mcp-debugger)

Before the fix, a javascript attach session on the running HTTP backend paused in sessionErrorToResult showed error.message = 'MCP error -32600: Cannot step over: …', error.detail = undefined, and the envelope carried the prefix. After dev_rebuild_and_restart, the same step_over on a never-started mock session returns:

{"success":false,"error":"Cannot step over: no active proxy for session 497e3ff0-…"}

Two usability defects surfaced by that probe are filed separately: #654 (attach pauses the target by default without the schema saying so) and #655 (js stack traces full of node_modules/phantom source-mapped frames).

Fixes #647

🤖 Generated with Claude Code

https://claude.ai/code/session_01SNhNB42Y55cgsknYTQb2Bm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!