mcp-doctor v0.4.0

mcp-doctor v0.4.0

mcp-doctor v0.4.0 expands passive server-author diagnostics, bounded
revision selection, and deterministic CI artifacts while preserving the
existing explicit authority gates for active work.

Passive server guidance

Passive inspect now reports structural, redacted findings for:

• missing or blank tool descriptions with MCP-QUALITY-001;
• placeholder or name-only tool descriptions with MCP-QUALITY-003;
• required input properties without a usable direct description with
  MCP-QUALITY-002; and
• non-empty credential-like string literals in direct property default,
  const, examples, or enum keywords with MCP-SECURITY-001.

The description checks use the documented finite A1 normalization v1
contract. Findings retain ordinal schema locations and fixed corrective prose,
not tool names, property names, descriptions, credential-like identifiers,
literal values, or raw schemas. The security finding remains independent of an
earlier primary diagnosis. These checks add no request, reference retrieval,
credential read, model evaluation, or tool call.

Bounded passive revision selection

Omitting --protocol-version for inspect now selects the finite auto mode.
It tries the compiled MCP 2026-07-28 discovery path and may enter one
transport-specific legacy transition only after the documented signal. STDIO
fully stops and reaps the first process before its one permitted legacy launch.
Streamable HTTP reuses the canonical endpoint, pinned addresses, peer checks,
trust, credentials, deadline, and aggregate budgets without re-resolution.

Explicit 2026-07-28, 2025-11-25, and 2025-06-18 passive selections remain
hard pins with one lifecycle and no fallback. Reports expose only fixed,
value-free selection evidence. They do not retain commands, paths, endpoints,
addresses, credentials, error prose, response bodies, catalog identifiers, or
server instructions.

Well-formed JSON-RPC rejection of the first lifecycle method is now diagnosed
at the revision layer instead of as a catalog failure. Bounded meta-validation
or validator-construction exhaustion after preliminary schema gates pass is
reported as incomplete MCP-SCHEMA-005 evidence rather than a false server
failure. Independent genuine failures still take precedence.

Deterministic report artifacts and CI

inspect, check, break, and reject can now write deterministic Markdown
and badge artifacts alongside JSON and JUnit from the same immutable redacted
result:

mcp-doctor inspect \
  --json-report artifacts/mcp-doctor.json \
  --junit-report artifacts/mcp-doctor.xml \
  --markdown-report artifacts/mcp-doctor.md \
  --badge-report artifacts/mcp-doctor-badge.json \
  -- node ./dist/server.js --stdio

Markdown uses mcp-doctor.markdown/v1. Badge output is fixed
mcp-doctor.badge/v1 Shields endpoint JSON containing only the label and the
run's pass, fail, or incomplete state. All destinations retain the
existing preflight, new-file, no-follow, no-overwrite, distinct-path,
all-or-nothing publication, rollback, cleanup, and aggregate-output bounds.

The source also includes a copyable least-permission GitHub Actions passive
preflight. Its synthetic fixture, exact revision, read-only permission, JSON
and JUnit paths, unconditional artifact upload, and unmasked diagnostic exit
are covered by repository policy tests. The starter remains pinned to the
already published 0.3.3 binary until a later source change can reference the
public 0.4.0 package.

Compatibility

This is a minor release because it adds multiple diagnostic and artifact
surfaces and changes omitted passive revision selection to bounded auto.
Existing command names, explicit revision pins, active authorization gates,
stable report schema names, exit meanings, and platform boundaries remain.

Two changes may affect automation:

• STDIO auto may start the exact selected command a second time after fully
  reaping the discovery process; use an explicit revision when one lifecycle
  and one process launch are required.
• Catalogs that previously passed may now warn for unusable guidance or fail
  for an exposed credential literal. Consumers of mcp-doctor.report/v1
  should continue to follow the documented outcome and ignore unknown optional
  fields.

Active commands retain MCP 2026-07-28 as the only implicit revision. Legacy
check and break still require an exact supported selection, and reject
remains current-revision only. No tool call, side effect, credential,
private-network access, or cleartext access is authorized implicitly.

Install the exact Cargo version with the committed dependency lock:

cargo install mcp-doctor --version '=0.4.0' --locked

Or build the immutable source through Homebrew on macOS or GNU/Linux:

brew install --build-from-source EnjoyableWork/tap/mcp-doctor

Native archives remain limited to GNU/Linux ARM64 and x64. Source installs are
tested on represented macOS, GNU/Linux, and Windows hosts. The release does not
add project-issued macOS or Windows binaries.

See the release integrity guide for the artifact, provenance,
and installed-channel publication contract.