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.

mcp-doctor v0.3.3

mcp-doctor v0.3.3

mcp-doctor v0.3.3 is a security patch for two independently bounded
resource-amplification paths.

Fragmented request-scoped SSE is now decoded incrementally. Each accepted byte
is scanned in order without reparsing prior chunks, while current-line,
current-event, payload, per-message, aggregate-output, and message-count state
remain bounded. CR, LF, CRLF, split UTF-8, comments, empty priming events,
notifications, server requests, EOF, and early matching responses retain their
existing protocol behavior.

Draft 2020-12 schema processing now charges its preliminary walk,
meta-validation, validator construction, local-reference fan-out, combinators,
instance access, strings, collections, equality, uniqueness, and pattern work
to schema_evaluation_steps. Pattern complexity—including counted repetition,
character-class ranges, reachable pattern fan-out, and all potentially
inspected instance text—is admitted before matching. Exhaustion produces the
existing typed limit and stops before an affected tool call.

Pattern validation now uses the bounded linear-time engine. Patterns requiring
backtracking-only constructs such as look-around or backreferences receive the
typed unsupported_linear_pattern diagnostic. This is a deliberate
resource-safety subset of Draft 2020-12 pattern syntax and should be considered
when upgrading a server that advertises those constructs.

Users of 0.1.0 through 0.3.2 should upgrade when diagnosing an endpoint,
process, or scenario that may supply adversarial SSE fragmentation or compact
schema/instance cross-products. Until upgraded, diagnose only trusted schemas
and avoid Streamable HTTP endpoints whose response framing is not trusted.

The fragmented-SSE and JSON Schema root causes retain separate advisory
records because their affected version ranges differ. Their public links are
added only in a post-publication closure update after the patched channels and
both coordinated advisories are public.

The canonical instruction-only Agent Skill is reissued with exact 0.3.3
identity and no new execution authority. A new host-support claim requires a
separate exact-version observation; the historical 0.3.2 evidence is not
silently extended to this patch.

Install the exact version with Cargo:

cargo install mcp-doctor --version '=0.3.3' --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
verified on represented macOS, GNU/Linux, and Windows hosts. The release does
not add a protocol revision, transport, diagnostic, output format, active
authority, or platform-signing claim.

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

mcp-doctor v0.3.2

mcp-doctor v0.3.2

mcp-doctor v0.3.2 makes the existing passive diagnostic workflow easier for
coding agents to discover without turning the product into an MCP server or
granting an agent new authority.

Portable Agent Skill

The release adds one canonical, instruction-only Agent Skill. It:

• checks the exact installed CLI version and stable compiled capabilities;
• requires one exact user- or repository-selected target;
• defaults to passive inspect --format json;
• explains the primary diagnosis, independent findings, causal skips, outcome,
  and exit from the stable redacted report;
• reads an existing report without rerunning its target;
• permits one explicitly requested correction and one byte-identical passive
  rerun; and
• refuses inferred targets, installations, secrets, check, break, and
  reject.

The versioned mcp-doctor-agent-skill-v0.3.2.tar.gz companion contains only
mcp-doctor/SKILL.md. Its exact digest is in the release SHA256SUMS, and its
build provenance is tied to the same annotated tag, workflow, and source commit
as the other immutable assets.

Installed help route

Top-level mcp-doctor --help links to the exact v0.3.2
coding-agent guide. Cargo, Homebrew, and GitHub archive
installation do not modify any coding-agent host; skill installation and
removal remain separate, explicit, digest-verified steps.

Scope

This patch adds no protocol revision, diagnostic check, active target authority,
MCP-server mode, marketplace requirement, IDE extension, daemon, SDK, hosted
service, dependency, silent installation, or broad agent-compatibility claim.
The CLI's process, network, credential, tool, side-effect, cleanup, redaction,
and reporter gates remain authoritative if a host ignores an instruction.

Install the exact Cargo version with the committed dependency lock:

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

mcp-doctor v0.3.1

mcp-doctor v0.3.1

mcp-doctor v0.3.1 is a security patch for authority-bearing local file
inputs and report artifact publication.

The patch binds scenario, custom-CA, snapshot, and aggregate reads to one exact
regular file opened without following a symbolic link or Windows reparse
point. Metadata and size decisions come from that opened handle; a second
no-follow identity check proves the selected path still identifies it before
the original handle is read. Replacement, disappearance, non-regular input,
or an unavailable native identity fails closed without retry or fallback.

Custom CA material is now read and validated before credential environment
resolution, DNS, or connection activity. Existing target, credential, tool,
effect, side-effect, schema, byte, redaction, and cleanup boundaries are
unchanged.

Report publication now records the complete native identity of each opened
stage handle, proves that its pathname still identifies that handle before
linking, and proves that the new destination has the same identity immediately
after linking. Cleanup and rollback remove only paths that still identify an
owned stage or output. A replaced stage or destination therefore fails the
artifact set without accepting or deleting the foreign entry; JSON, JUnit, and
aggregate output retain the same no-overwrite and all-or-nothing behavior.

Users of 0.2.0 or 0.3.0 should upgrade when another process or principal
could replace entries in a directory containing a selected scenario, CA
bundle, snapshot, aggregate input, or report destination. Until upgraded, keep
those files and destinations in directories that cannot be modified by another
principal or concurrent process for the complete diagnostic run.

Install the exact version with Cargo:

cargo install mcp-doctor --version '=0.3.1' --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
verified on represented macOS, GNU/Linux, and Windows hosts. The release does
not add a protocol revision, transport, diagnostic, output format, or signing
claim.

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

mcp-doctor v0.3.0

mcp-doctor v0.3.0

mcp-doctor v0.3.0 turns several common authoring and CI workflows into
bounded, explicit product paths while keeping the existing passive-first and
exact-authorization contracts.

It adds:

• explicit passive inspect support for MCP 2025-11-25 and 2025-06-18
  over STDIO and Streamable HTTP, with no auto-detection, retry, fallback, or
  active legacy tool calls;
• exact-opt-in current-revision contract snapshots and deterministic offline
  diffs, with a deliberate sensitive-artifact acknowledgement and no target
  activity during comparison;
• simultaneous JSON and JUnit report files from the same redacted diagnostic
  run, without restarting a server or replaying an authorized tool call;
• conservative offline aggregation of one through 32 stable JSON reports,
  preserving failures, incomplete outcomes, primary diagnoses, independent
  safety findings, and causal skips without contacting a target; and
• correct protocol-layer diagnosis when a current-revision Streamable HTTP
  server returns the exact structured unsupported-version response.

The unsupported-version correction accepts only the bounded specification
shape. It never renders the server's error prose or offered revision values,
and it does not retry, initialize, downgrade, or fall back.

Install the exact version with Cargo:

cargo install mcp-doctor --version '=0.3.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
verified on represented macOS, GNU/Linux, and Windows hosts. Active check and
break remain limited to MCP 2026-07-28. This release does not add SARIF,
become a general security scanner, claim broad real-server legacy
compatibility, or ship project-issued macOS or Windows binaries.

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

mcp-doctor v0.2.0

mcp-doctor v0.2.0

mcp-doctor v0.2.0 expands the passive local preflight into a bounded,
explicitly authorized diagnostic workflow for local STDIO and remote
Streamable HTTP MCP 2026-07-28 servers.

It adds:

• reviewed check scenarios for 1–100 ordered calls to one exact tool, gated
  by matching --allow-tool authority and separate side-effect consent;
• direct, zero-redirect and zero-retry Streamable HTTP with pinned bounded
  resolution, verified TLS, exact private/cleartext/credential gates, and no
  automatic OAuth flow;
• deterministic break generation for bounded, schema-valid cases against one
  redundantly selected and authorized tool;
• authoritative, schema-backed mcp-doctor.report/v1 JSON across passive,
  reviewed active, generated, STDIO, and HTTP journeys; and
• a deterministic, bounded JUnit-compatible projection that maps each
  diagnostic check to one test case without rerunning the target.

Human, JSON, and JUnit output derive from the same redacted result. Stable JSON
preserves the full contract; JUnit preserves safe findings, causal skips,
outcomes, and exit metadata in the common subset accepted by the reviewed
Jenkins and GitLab consumers. The process exit remains the portable CI gate.

Install the exact version with Cargo:

cargo install mcp-doctor --version '=0.2.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
verified on represented macOS, GNU/Linux, and Windows hosts. This release does not add SARIF.
It does not become a general security scanner. It also does not implement older MCP
revisions, call a tool without exact run authority, contact a real endpoint in
the default suite, or ship project-issued macOS or Windows binaries.

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

mcp-doctor v0.1.0

mcp-doctor v0.1.0

The first public mcp-doctor release delivers a safe, noninteractive preflight
for local MCP servers over STDIO.

It can:

• discover an MCP 2026-07-28 server without sending initialize or calling
  a tool;
• validate JSON-RPC envelopes, advertised capabilities, paginated tools,
  prompts, resources, resource templates, and Draft 2020-12 tool schemas;
• identify the earliest actionable failing layer while preserving independent
  safety failures and explaining causally skipped checks;
• enforce bounded startup, discovery, request, response, output, schema,
  shutdown, and total-run limits; and
• emit equivalent human output and experimental
  mcp-doctor.report/v1alpha1 JSON with untrusted values and secrets removed.

The release contains the exact Cargo source package and source-building
Homebrew formula, native GNU/Linux ARM64 and x64 archives, SHA-256 checksums,
target SPDX 2.3 SBOMs, and build-provenance attestations. Every represented
installation channel is independently smoke-tested against a passive synthetic
server.

Install the exact version with Cargo:

cargo install mcp-doctor --version '=0.1.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 are provided only for GNU/Linux ARM64 and x64. This release
does not call tools, connect to remote HTTP endpoints, implement older MCP
revisions, claim official MCP conformance, or ship project-issued macOS or
Windows binaries. check, break, and Streamable HTTP remain product
direction, not implemented v0.1.0 behavior.

See the release integrity guide for the exact asset contract
and verification commands.