refactor(mcp): introduce a versioned protocol and transport adapter boundary

[oaslananka]

Summary

Introduce and complete the extension-side MCP protocol, lifecycle, and transport boundaries before adopting the final 2026-07-28 protocol revision.

Context

The extension previously concentrated transport execution, initialize/session lifecycle, retries, timeout/SSE parsing, compatibility negotiation, capability normalization, and domain result normalization in apps/vscode-extension/src/mcp/mcpClient.ts.

The incremental boundaries are now in place without prematurely claiming final 2026-07-28 compatibility.

Completed phases

• Phase 1: add the strict versioned protocol adapter registry, production 2025-11-25 adapter, independent HTTP JSON-RPC transport, structured mismatch diagnostics, and non-selectable 2026 draft fixture in PR 501.
• Phase 2: extract request IDs, coalesced discovery, protocol execution, response metadata, session persistence, and stateless-session isolation into the lifecycle coordinator and narrow VS Code Memento adapter in PR 576.
• Phase 3: add the machine-enforced final-protocol activation record, stable-artifact evidence validation, ADR status parity, path containment, RC/prerelease rejection, and dated preflight evidence in PR 577.
• Phase 4: canary the exact published kicad-mcp-pro 3.29.1 artifact in its opt-in 2026-07-28-rc lane, validating stateless server/discover, 24-tool tools/list, routing metadata, TTL/private-cache semantics, deterministic names, and no protocol session in PR 578.

Current architecture contract

• Production TypeScript graph: 160 modules, 0 import cycles.
• mcp/protocol/ owns protocol-version selection, discovery requests, version-specific headers, negotiated-version validation, request IDs, discovery coalescing, response metadata, and lifecycle-aware session reuse.
• mcp/transport/ owns JSON-RPC serialization, Streamable HTTP, timeout/retry policy, JSON/SSE parsing, opt-in legacy SSE fallback, and traffic evidence without interpreting sessions.
• mcp/adapters/vscodeProtocolSessionStore.ts hides the current persisted session key behind a narrow store contract.
• mcp/mcpClient.ts retains endpoint configuration, VS Code connection state, compatibility cards, diagnostics, warnings, and domain result normalization.
• 2025-11-25 remains the only production-selectable protocol.
• Stateless adapters cannot receive or persist legacy session state.
• compatibility.yaml records 2026-07-28 as a blocked activation target; the contract rejects selecting it until every final evidence field is valid.
• Activation requires the official stable specification, stable Python SDK, stable published protocol schemas, a stable KiCad MCP Pro artifact advertising the target, the checked-in stateless adapter, published-artifact real-pair evidence, and ADR 0008 as Accepted.
• RC, beta, draft, missing-file, external-path, registry, and ADR-status drift evidence fails closed.
• Cross-repo Compatibility resolves the exact stable PyPI server version and runs the published-artifact RC canary before compatibility checks.
• The RC canary is isolated from the production adapter registry; compatibility.yaml remains blocked and 2025-11-25 remains the only selectable production protocol.

Upstream status (verified 2026-08-02)

• The official MCP 2026-07-28 specification release/tag is published and stable.
• Python MCP SDK 2.0.0 is the stable v2 line and explicitly supports 2026-07-28 and every earlier revision.
• The published kicad-mcp-pro 3.29.2 artifact passes this repository's stateless canary: protocol 2026-07-28, 24 deterministic tools, private-cache responses, and no protocol session.
• KiCad MCP Pro's stable compatibility contract still advertises 2025-11-25 as active and 2026-07-28 as the next protocol. Production activation in this repository therefore remains intentionally blocked.

Remaining work

• Promote 2026-07-28 in kicad-mcp-pro from the opt-in compatibility lane to the active GA protocol and publish a stable artifact whose compatibility metadata advertises it as active.
• Verify and consume a protocol-schema release based on the final specification, including the matching @oaslananka/kicad-protocol-schemas contract used by the extension.
• Implement and production-register the final stateless extension adapter from the published specification while preserving the 2025-11-25 compatibility path.
• Produce final GA published-artifact real-pair evidence and change mcp.activation.state from blocked to active in the coordinated compatibility update.
• Change ADR 0008 from Proposed to Accepted with the final implementation decision, migration evidence, and rollback behavior.

Acceptance criteria

• Current 2025-11-25 behavior remains covered and backward compatible.
• Transport concerns are separated from capability/domain normalization.
• Protocol lifecycle behavior is selected through an explicit versioned adapter.
• Session-based 2025 behavior does not leak into a stateless adapter.
• Fixtures cover the current protocol and the expected 2026 discovery/request envelope without asserting unfinalized details as production truth.
• Unsupported or mismatched protocol versions produce structured, actionable diagnostics.
• Cross-repo artifact tests verify the extension against supported published KiCad MCP Pro versions.
• No direct source dependency on the external MCP server repository is introduced.
• Unit, integration, cross-platform, and real-pair compatibility gates pass for the completed boundaries.
• Premature final-protocol activation fails closed on incomplete, RC, prerelease, path, registry, and ADR evidence.
• The official stable MCP 2026-07-28 specification is published.
• Python MCP SDK 2.0.0 is stable and explicitly supports 2026-07-28.
• The exact published kicad-mcp-pro 3.29.2 compatibility lane is behavior-tested without making the target protocol production-selectable.
• A stable KiCad MCP Pro artifact advertises 2026-07-28 as its active GA protocol.
• The final published 2026-07-28 extension adapter is validated and activated through compatibility metadata.
• ADR 0008 is updated with the final implementation decision and migration evidence.

Validation

corepack pnpm run check:protocol-schemas
corepack pnpm run check:compatibility-contract
corepack pnpm run check:mcp-2026-rc-artifact -- --version 3.29.2
corepack pnpm run check:kicad-studio

Risk

High. Final protocol activation remains intentionally blocked until the specification and compatible published server artifacts are final.

---

This repo is using Opire - what does it mean? 👇

💵 Everyone can add rewards for this issue commenting /reward 100 (replace 100 with the amount).
🕵️‍♂️ If someone starts working on this issue to earn the rewards, they can comment /try to let everyone know!
🙌 And when they open the PR, they can comment /claim #492 either in the PR description or in a PR's comment.

🪙 Also, everyone can tip any user commenting /tip 20 @oaslananka (replace 20 with the amount, and @oaslananka with the user to tip).

📖 If you want to learn more, check out our documentation.

[oaslananka]

Phase 1 is ready for review in #501. The PR establishes the production-safe versioned adapter/transport boundary, preserves 2025-11-25, passes real-pair and all cross-platform required checks, and deliberately keeps the 2026-07-28 RC non-selectable. This issue remains open for the final specification-driven adapter, coordinated compatibility activation, published-server evidence, and final ADR implementation decision.