feat(mcp): migrate runtime, CI and documentation contracts for SDK 2.x #389

Problem and evidence

Dependabot PR #380 replaces the intentional mcp==1.30.0 minimum-profile constraint with 2.3.0 while the project still requires mcp>=1.30,<2, so minimum-profile installs are unsatisfiable. PR #384 widens the manifest to <3, but the runtime still imports removed mcp.server.fastmcp.FastMCP, and CI explicitly rejects non-1.x latest SDKs. Combining the two pin changes does not migrate the server.

The owner requested a separate, coherent runtime/CI/documentation migration. No existing open issue covers SDK-major compatibility (#360 is separate handoff/observation research).

Scope and intended compatibility

Support stable MCP SDK 1.x from 1.30 and stable SDK 2.x from 2.3. Exclude SDK 2.0–2.2: their server exposes subscriptions/listen without a public off switch; SDK 2.3+ provides MCPServer(subscriptions=False). The candidate extra is mcp>=1.30,<3,!=2.0.*,!=2.1.*,!=2.2.*. Prerelease/development SDKs are not accepted by startup. Keep core Python 3.9 dependency-free, optional MCP Python 3.10+, minimum SDK 1.30.0 and ordinary CLI/native behavior unchanged. Widening the optional range is gated on working startup, wire contracts and integration tests rather than dependency resolution alone.

• Add a bounded SDK-compatible server/type boundary for 1.x and 2.x; avoid hiding real dependency/import failures with broad fallback exceptions.
• Preserve public tool names/signatures, project result JSON and camelCase wire aliases, policy schemas/capability checks, separate host approvals, per-destination allowlists, size/time limits, cancellation/owned-child cleanup and unknown/no-automatic-resend behavior. Do not add caller identity, native permission, ACK/handoff or platform support.
• Make CI explicitly distinguish minimum (1.30.0), latest1 (>=1.30,<2), minimum2 (2.3.0) and latest2 (>=2.3,<3): 24 cells across macOS/Linux and Python 3.10/3.13/3.14. Preserve the true 1.30.0 minimum constraint, validate installed major/profile versions, run installed stdio contracts and per-profile audits on Mac/Linux across the existing Python matrix. Exercise both directions of opposite-major client/server negotiation plus same-major modern negotiation. SDK-generated envelopes/capability fields may differ by negotiated protocol; project result payload schema 1 remains unchanged.
• Update dependency guards, runtime/integration fixtures and current English/Korean/Japanese/Simplified Chinese docs together. Describe this as unreleased work after v1.4.2, not support already present in the immutable published release. Preserve historical version-pinned records and independent skill ownership/floors.

Acceptance

• Both supported SDK branches start and expose the same authorized tool surfaces; current results are tested at the wire boundary, not merely with imports/mocks.
• Existing policy refusals, send/preflight/diagnostics/preset limits and cancellation/cleanup regressions still hold. No assertion weakening, implicit retries or permission expansion.
• Minimum and SDK-major CI contracts agree with the manifest; version outputs/audits and matrix evidence identify the actual tested SDKs.
• Updated current docs/translations preserve platform/version/permission/submission/ACK boundaries and clearly mark the unpublished candidate scope.
• Independent CLI technical review and user-selected Gemini 3.8 Flash translation QA are source-checked before a separate PR; exact-head CI/automatic reviews are checked.

Boundaries

Refs #380, #384. These Dependabot PRs remain separate and are not merged or closed by this issue. The migration PR does not authorize merge, package release, global installation, service/configuration changes, live agent/SSH messages or protection bypasses. #360 and other Long-term/native/handoff research remain separate.

Implementation checkpoint (2026-11-09)

PR #390 implements the isolated migration at head 8069571283ea1afce2544e62329bc8de08c2a196.

• SDK 1.30.0 and 2.3.0 on Python 3.14.10: 111 integration tests run in each environment (110 passed, one existing external-volume secure-store positive skip). Both opposite-major negotiation directions actually ran. The final Unicode/raw-boundary set passed eight tests per SDK without skips.
• SDK 2 modern response metadata is included in conservative 64 KiB accounting. A mutation removing it fails the regression (actual modern result 65,575 bytes, limit 65,536). Legacy responses gain no metadata fields.
• Python 3.9 without the optional SDK: 111 tests run (91 passed, 20 optional skips); MCP entry point refuses Python <3.10 with empty protocol stdout.
• Documentation checks: 93 passed. Generator, syntax and diff checks passed.
• Fresh read-only Claude Opus 5.5 and Gemini 4 Argon paired technical reviews were completed before PR creation; Gemini 3.8 Flash reviewed all four-language guides/README changes and the final added excerpts. Source adjudication, input hashes/models and post-review limits are recorded in the PR body.

Exact-head CI run 42573950718 completed successfully: 49 CI jobs, including all 24 MCP cells. Every MCP cell ran the opposite-major client and normal-filesystem secure-store positive test successfully; resolved SDKs were 1.30.0 and 2.3.0. All 56 aggregate PR checks succeeded. Automatic code/security statuses are completed, with no published findings or unresolved threads (code finding flags false, security finding flags null). This issue stays open for owner review/merge; no automatic-closing reference was added. No native-agent/SSH/ACK or operational acceptance is claimed. No merge or release has been performed.