Motivation
Nine language adapters, each with external prerequisites — and nearly all real-world setup friction is environmental, not a bug in the server: debugpy missing from the active Python, dlv not on PATH, JDK too old, NETCOREDBG_PATH unset, kernel.yama.ptrace_scope blocking attach on Linux, a wrong volume mount in container mode. Today the user (often an AI agent) discovers these one failure at a time, and the prerequisites are scattered across per-language READMEs.
Proposal
1. mcp-debugger doctor CLI subcommand
Prints one table — adapter → runtime found (path + version) → debug backend found → verdict + fix hint:
- python: interpreter resolution (
PYTHON_PATH / auto-detect), python -m debugpy --version
- javascript: Node ≥ 22, vendored js-debug present
- ruby: ruby/rdbg resolution (
RUBY_PATH/RDBG_PATH), debug gem version
- go:
go + dlv on PATH, dlv DAP support
- java:
java/javac ≥ 21 (JAVA_HOME)
- dotnet: SDK + netcoredbg resolution (
NETCOREDBG_PATH / PATH)
- rust / cpp: CodeLLDB resolution order (vendored → env → platform package), compiler presence (informational, for cpp source-file launch)
- platform: Yama
ptrace_scope (Linux attach), container-mode detection + /workspace mount sanity
Plus --json for machine consumption, and an exit code reflecting whether any requested language is broken. Much of the probing logic already exists in the adapters' availability/validateExecutable paths — doctor should reuse it, not duplicate it.
2. One consolidated diagnostics guide
A single docs/diagnostics.md gathering prerequisites and failure signatures in one place: per-language runtime requirements, Yama/ptrace, container mounts, dryRunSpawn, DAP_TRACE, log file locations — linked from the README and from error messages where a doctor-style hint fits.
The list_supported_languages tool already reports per-mode availability; doctor is the human/agent-facing "why is it unavailable and how do I fix it" complement.
Motivation
Nine language adapters, each with external prerequisites — and nearly all real-world setup friction is environmental, not a bug in the server: debugpy missing from the active Python,
dlvnot on PATH, JDK too old,NETCOREDBG_PATHunset,kernel.yama.ptrace_scopeblocking attach on Linux, a wrong volume mount in container mode. Today the user (often an AI agent) discovers these one failure at a time, and the prerequisites are scattered across per-language READMEs.Proposal
1.
mcp-debugger doctorCLI subcommandPrints one table — adapter → runtime found (path + version) → debug backend found → verdict + fix hint:
PYTHON_PATH/ auto-detect),python -m debugpy --versionRUBY_PATH/RDBG_PATH), debug gem versiongo+dlvon PATH, dlv DAP supportjava/javac≥ 21 (JAVA_HOME)NETCOREDBG_PATH/ PATH)ptrace_scope(Linux attach), container-mode detection +/workspacemount sanityPlus
--jsonfor machine consumption, and an exit code reflecting whether any requested language is broken. Much of the probing logic already exists in the adapters' availability/validateExecutablepaths — doctor should reuse it, not duplicate it.2. One consolidated diagnostics guide
A single
docs/diagnostics.mdgathering prerequisites and failure signatures in one place: per-language runtime requirements, Yama/ptrace, container mounts,dryRunSpawn,DAP_TRACE, log file locations — linked from the README and from error messages where a doctor-style hint fits.The
list_supported_languagestool already reports per-mode availability; doctor is the human/agent-facing "why is it unavailable and how do I fix it" complement.