Prepare support for MCP 2026-07-28 spec while preserving legacy compatibility

[leehack]

Status — 2026-07-22

The MCP 2026-07-28 implementation and pre-final-spec release hardening are on main. Stable publication remains intentionally blocked until the official final Core and Tasks releases are available and reviewed.

Current release train:

• SDK source: mcp_dart 2.3.0-dev.3
• CLI source: mcp_dart_cli 0.2.0-dev.3
• Stable targets: SDK 2.3.0, then CLI 0.2.0
• SDK minimum: Dart 3.4
• CLI minimum: Dart 3.12
• Default profile: McpProtocol.stable prefers MCP 2026-07-28 discovery and falls back to legacy initialization
• Exact legacy opt-in: McpProtocol.legacy
• Strict 2026-only opt-in: McpProtocol.require2026

The official MCP repository still exposes only the 2026-07-28-RC prerelease. The final release is scheduled for July 28, 2026. Specification PR #2776, which may change stdio legacy-fallback guidance, remains open and currently has merge conflicts.

See the checked-in day-0 release runbook for the exact promotion and publication procedure.

Completed implementation

• Add MCP 2026-07-28 stateless discovery and per-request metadata.
• Preserve MCP 2025-11-25 and earlier initialization/session flows.
• Implement dual-era default negotiation with bounded discovery fallback.
• Implement stateless Streamable HTTP routing, validation, cancellation, and transport lifecycle behavior.
• Add subscriptions/listen, multi-round input_required results, and the io.modelcontextprotocol/tasks extension model.
• Retain legacy subscription, logging, initialization, and task APIs for older peers.
• Align optional client/server identity with specification PR #3002, including result _meta server identity.
• Implement self-contained JSON Schema Draft 2020-12 validation while preserving declared Draft 7 behavior.
• Add official 2025-11-25 and 2026-07-28 conformance gates.
• Add TypeScript, Python, browser, Flutter Web, stdio, and Streamable HTTP interoperability coverage.
• Add minimum-Dart and public API compatibility gates against mcp_dart 2.2.2.
• Publish SDK and CLI dev.3 rehearsals and all standalone CLI binary platforms.
• Document the transition, interoperability matrix, specification coverage, migration behavior, and day-0 release procedure.
• Remove the SDK's json_schema and quiver runtime dependencies without reducing Draft 2020-12 or Draft 7 conformance coverage (#326).

Current validation evidence

Current main commit ea7ffc30 is green:

• Core SDK workflow: Dart 3.4 minimum, API compatibility, both protocol-era conformance suites, official JSON Schema suites, examples/platforms, publish dry-run, and Pana.
• CLI workflow: Dart 3.12 minimum, cross-language fixtures, compile/smoke tests, package export validation, and Pana.
• MCP 2026-07-28 interoperability: TypeScript, Python, browser, and Flutter coverage on the coordinated dev.3 release commit b2b0993c.
• CodeQL: green.

The coordinated dev.3 rehearsal completed end to end on 2026-07-22: SDK 2.3.0-dev.3 and CLI 0.2.0-dev.3 are published, the release workflows succeeded, and Linux x64, macOS x64/arm64, and Windows x64 CLI binaries are attached. The CLI scores 160/160 on pub.dev; the newly published SDK analysis is still pending.

Current immutable review inputs:

• Core specification: 88191b9f574d67d553ea9372278a14e09d762f55
• Tasks extension: 2c1425d9a288b9b1f489430fe1e00bb392b47e48
• Conformance: 0.2.0-alpha.9; the three exact pre-#3002 stateless diagnostics remain recorded, while merged conformance PR #403 source passes without expected failures.
• Published TypeScript split SDK: 2.0.0-beta.5
• Published Python SDK/types: 2.0.0b2; the published reverse-client remains a documented pre-#3002 gap.

These peer/referee gaps are upstream prerelease drift, not known missing core behavior in the Dart implementation.

Dependencies and repository security

• The Dart SDK no longer depends on json_schema or quiver; validation is implemented in-package and remains covered by the official Draft 2020-12, Draft 7, and Draft 7 format suites.
• PR #327 updated test-only fast-uri to 3.1.4 and closed both high-severity alerts.
• PR #328 overrides the TypeScript interoperability fixture's transitive @hono/node-server to 2.0.11. It merged as 32e0cfc768d8aa7689801e5157508d88596e3ff1; post-merge Core, CLI, CodeQL, minimum-SDK, API-compatibility, platform, example, conformance, interoperability, publish-validation, and Pana checks are green.
• Zero Dependabot alerts remain.
• No open CodeQL or secret-scanning alerts remain.

Compatibility contract

• MCP 2025-11-25 remains supported and covered by official conformance.
• McpProtocol.legacy preserves the initialization-only flow for applications that cannot probe discovery.
• Deprecated latestProtocolVersion and supportedProtocolVersions retain their mcp_dart 2.2 meanings.
• defaultProtocolVersion and allSupportedProtocolVersions represent the dual-era default profile.
• Existing 2.2.2 registration, callback, logging, request metadata, and StartSseOptions APIs remain available.
• The public API compatibility gate reports no unapproved breaking change against mcp_dart 2.2.2.

Intentional observable changes that must remain in the release notes:

• The SDK minimum increases from Dart 3.0 to Dart 3.4.
• The default profile probes server/discover before legacy initialization; a silent body-only peer can delay fallback by up to five seconds.
• OAuth metadata, redirect, issuer, and token validation are stricter.
• JSON Schema parsing and validation are stricter and dialect-aware.
• DiscoverResult.serverInfo is nullable for anonymous 2026 servers; this affects 2.3 prerelease adopters rather than the stable 2.2 API surface.

Remaining work

All actionable pre-final-spec work is complete. Only day-of work remains:

• Wait for the official final 2026-07-28 Core specification and Tasks extension releases.
• Freeze both final SHAs and diff them against the checked-in Core and Tasks refs.
• Audit the final dated schemas, examples, and normative documents, including Tasks failed-state errors, timing fields, capability error codes, and subscription termination.
• Confirm the outcome of specification PR #2776.
• Adopt the final compatible conformance release/source and remove obsolete expected diagnostics; no unexplained failure may remain.
• Re-run both-direction interoperability with the final available TypeScript and Python SDK releases/sources.
• Promote protocol maturity constants while preserving deprecated 2.2 compatibility aliases.
• Promote SDK metadata and changelog to 2.3.0; replace prerelease snippets, links, and maturity wording.
• Run the complete minimum-SDK, API-compatibility, conformance, interop, examples, publish-dry-run, and Pana gate on the exact release commit.
• Confirm a fresh valid RELEASE_PAT, exact-SHA release authorization, and zero open security alerts before creating the stable tag.
• Publish mcp_dart 2.3.0 first and verify a public consumer smoke test.
• Promote CLI metadata/templates to 0.2.0 and mcp_dart ^2.3.0.
• Validate the CLI against the published SDK, run Pana, publish the CLI, build binaries, and verify public installation.

Release decision

Target a day-0 stable release, but do not publish by calendar alone. Ship only after the final Core and Tasks deltas are understood and the complete gate passes. If the final specification or coordinated SDK releases introduce unvalidated behavior, delay publication until it is covered.

[leehack]

Status update as of 2026-06-04:

The 2026-07-28 RC support work is now available for testing from the dev release train. This is intentionally not promoted as the stable/latest release while the MCP spec is still RC/draft.

Published dev packages:

• SDK: mcp_dart 2.3.0-dev.0
  • GitHub prerelease: https://github.com/leehack/mcp_dart/releases/tag/v2.3.0-dev.0
  • pub.dev has the dev version published; stable latest remains 2.2.0.
• CLI: mcp_dart_cli 0.2.0-dev.0
  • GitHub prerelease: https://github.com/leehack/mcp_dart/releases/tag/mcp_dart_cli-v0.2.0-dev.0
  • pub.dev has the dev version published; stable latest remains 0.1.9.
  • CLI release assets are attached for Linux x64, macOS x64, macOS arm64, Windows x64, plus mcp-developer.SKILL.md.

Install/test commands:

dart pub add mcp_dart:2.3.0-dev.0
dart pub global activate mcp_dart_cli 0.2.0-dev.0

Current compatibility posture:

• Default SDK behavior remains aligned with the current stable MCP spec path.
• 2026-07-28 RC/draft behavior is explicitly opt-in for testing.
• Public APIs were kept strongly typed; we avoided exposing broad Object-typed APIs for normal user-facing flows.
• 2026-only APIs/features are documented and marked as draft/RC where applicable.
• CI now runs both 2025 conformance and 2026 RC conformance gates on the dev branch/release train.

Release workflow status:

• Dev release prep PR merged: Prepare dev release workflow #275
• CLI binary runner fix merged after the first binary workflow got stuck on a retired macOS runner label: Fix CLI binary workflow runner labels #276
• Replacement CLI binary workflow passed and attached the release assets: https://github.com/leehack/mcp_dart/actions/runs/26945496556

Remaining before stable promotion:

• Wait for the official MCP 2026-07-28 spec release/tag.
• Re-check any spec deltas against the final published spec.
• Re-run the full 2025 + 2026 conformance suite and interop checks.
• Only then promote this work from the dev release train into a stable release and decide whether/when 2026 becomes the default protocol target.

[leehack]

Day-zero pre-release work is now consolidated in draft PR #325: #325

Do not merge without explicit maintainer approval. The PR is based on current main and commit 9b618f80cdd23f35064571888a5be104e483dc92.

What is now complete before the final upstream release:

• MCP 2026-07-28 dual-era behavior, protocol direction, identity, Tasks, subscriptions, schemas, structured results, W3C reserved metadata, and transport lifecycle were re-audited and hardened.
• 2.2.2 compatibility aliases and APIs remain; SDK minimum is Dart 3.4 and CLI minimum is Dart 3.12.
• Direct runtime dependency constraints are current; json_schema remains runtime-required for Draft 2020-12/Draft 7 validation.
• Full SDK suites pass on exact Dart 3.4.0 and current Dart with both oldest-compatible and newest-resolvable graphs.
• CLI passes on exact Dart 3.12.0 and current Dart.
• Official 2025 server/client conformance is fully green.
• Official 2026 alpha.9 behavior is green except the exact known pre-#3002 referee mismatch; the corrected immutable post-#3002 referee passes with no failures.
• JSON Schema suites, TypeScript/Python/browser/Flutter interop, public API comparison, examples, docs, security/provenance fixtures, publish dry-runs, dartdoc, and Pana are green.
• Final adversarial review found no remaining actionable pre-release issue.

Current immutable review inputs are Core 88191b9f574d67d553ea9372278a14e09d762f55 and Tasks 2c1425d9a288b9b1f489430fe1e00bb392b47e48.

The only remaining work is deliberately day-of-only: freeze/diff the official final Core and Tasks inputs, reconcile their final ambiguous wire text, adopt final conformance and published peer versions, promote stable metadata/constants/docs, set the explicit final-review acknowledgements, confirm a fresh valid RELEASE_PAT, and run exact-SHA CI before publication. The new release gates block stable tags until those acknowledgements are complete.

[leehack]

Day-zero readiness update (2026-07-21)

Draft PR #325 now contains all pre-final-spec work found by the release audit and remains intentionally unmerged: #325

Exact head e879df860a6b7571b56ff6ee5256eee3750d9e56 is green in all four PR workflows:

• Core SDK (including Dart 3.4 minimum, published-2.2.2 API compatibility, 2025/2026 conformance, JSON Schema suites, Windows/macOS, examples, package dry run, and Pana)
• CLI (including exact Dart 3.12.0, exported package validation, conformance, and Pana)
• MCP 2026-07-28 interoperability
• Streamable HTTP lifecycle stress

The final audit also closed strict discovery cache hints, exact application/json request media-type handling, malformed successful discovery fallback, stdio broken-pipe/restart termination, exported Dartdoc stable-release scanning, and CLI binary release authorization/upload races. Two independent final re-reviews found no remaining P0/P1/P2 issues. Project coverage increased from 86.41% to 86.64%.

Compatibility remains deliberate: the SDK stays at Dart 3.4, the CLI at Dart 3.12, 2026-07-28 remains the default profile with 2025-11-25 fallback, and the public API comparison has no unapproved break against 2.2.2. json_schema remains required for runtime Draft 2020-12/Draft 7 contract validation.

Only the explicitly external day-of gates remain: review the final Core/Tasks tag delta and ambiguities, adopt final conformance and peer SDK releases, promote stable metadata/docs, install a fresh valid RELEASE_PAT, then publish SDK before CLI after maintainer-approved merge.