mcp-config-doctor 0.1.0

Read-only static diagnostics for local stdio MCP configuration

MCP Config Doctor 0.1

MCP Config Doctor is a local, read-only static scanner for one named MCP server. It checks known configuration surfaces for Claude Desktop, Claude Code, Codex, and VS Code, then prints deterministic findings and manual next steps.

Version 0.1.0 is a deliberately narrow public beta. It performs static checks only, makes no runtime-success promise, and does not include checkout or license enforcement. USD 19 remains a pricing hypothesis rather than a current charge.

Install and run locally

Python 3.11 or newer is the supported runtime. The package has no runtime dependencies and does not require network access.

python3 -m venv .venv
.venv/bin/pip install .
mcp-doctor scan --server filesystem

Narrow the scan or emit machine-readable output:

mcp-doctor scan --server filesystem --client codex --format json

The command prints the paths it checked, but replaces the home and project roots with ~ and <project>. It never prints environment values or argument values.

What v0 checks

• known user and project/workspace configuration locations;
• duplicate, shadowed, absent, and ambiguous-scope definitions;
• local stdio command resolution in the current process environment;
• configured cwd, path-like arguments, and named environment references;
• wrapper/no-TTY and container/localhost risk patterns;
• malformed, duplicate-key, unreadable, oversized, and unsupported configs;
• text and JSON reports using the same versioned finding catalog.

The full path matrix is in docs/config-matrix.md, and the stable code contract is in docs/findings.md.

Exit codes

• 0: reliable static scan with no actionable FAIL; warnings may remain.
• 1: reliable scan found at least one actionable FAIL.
• 2: invalid input, parsing, permission, unsupported transport/shape, or ambiguous precedence prevented a reliable conclusion.

Safety and privacy boundary

The installed mcp-doctor command only reads bounded supported config files and uses filesystem metadata plus the current process environment for static checks. It contains no network, subprocess-launch, file-write, installer, elevation, or auto-fix path. It does not start an MCP server, invoke JSON-RPC, call a tool, or claim that a GUI client inherits the shell's environment.

Environment values are inspected only for empty/present status and placeholder resolution. They are never retained in the report. Command arguments are not rendered. No telemetry is collected by the CLI; funnel measurement belongs to external repository, package, checkout, and support surfaces rather than this command. The external event names and data boundary are recorded in metrics/event-contract.json.

See SECURITY.md for the exact threat and disclosure boundary.

Known limitations

• Static checks cannot prove client or server runtime behavior.
• Claude Desktop's Linux path is a compatibility convention tested by v0, not a claim that Anthropic ships Claude Desktop on every Linux environment.
• VS Code manages user profiles; v0 checks the default stable profile path and the current workspace, not every named, portable, Insiders, or remote profile.
• VS Code's official MCP docs distinguish user/workspace scopes without defining deterministic duplicate-name precedence. v0 therefore returns exit 2 when the same server appears in both.
• Codex project configuration is subject to project trust.
• Python 3.9/3.10 source execution can parse Codex only when a compatible tomli module is already present; packaged support starts at Python 3.11.
• Remote HTTP/SSE, OAuth, client-specific runtime bugs, and third-party server correctness are explicit non-goals.

Verify

From this product directory:

python3 -m pip install --no-deps -e .
python3 -m unittest discover -s tests -v
python3 scripts/dry_run.py

Uninstalling the package removes the product. The CLI creates no state, edits no configuration, and has no hosted user data to migrate or delete.