Issue #259 opened: V3 Epic: migrate to MCP TypeScript SDK v2 + spec 2026-07-28

Why

The MCP spec revision 2026-07-28 ships on 28 July 2026 alongside a full TypeScript SDK v2 rewrite (currently 2.0.0-beta.3). This is the natural V3 boundary for coolify-mcp: adopt the new SDK, pick up the extensions framework, and shed deprecated surface. We're currently on SDK 1.x (^1.23) with the legacy server.tool() registration.

What changes in SDK v2 / spec 2026-07-28

• Package split: @modelcontextprotocol/sdk → @modelcontextprotocol/server + @modelcontextprotocol/client. The McpServer + registerTool() shape survives, so a 2.x registerTool migration (#260-style prep) carries over.
• Standard Schema: no longer zod-locked (zod v4, Valibot, ArkType all work). We're already on zod 4 — low friction.
• Stateless protocol core: initialize/initialized handshake removed; capabilities travel in _meta; new server/discover method. stdio impact is minimal — the SDK handles the handshake changes; this mostly matters if we ever ship a remote/HTTP variant.
• Extensions framework: reverse-DNS-namespaced, independently versioned. The two official launch extensions (Tasks, MCP Apps) get their own issues.
• Deprecations: Roots, Sampling, and protocol-level Logging are deprecated (12-month removal window). We use none of them — nothing to unwind.
• Elicitation redesign: InputRequiredResult pattern (client retries with collected answers) replaces held-open server→client requests; SDK v2 exposes inputRequired.elicit().

Timeline & support window

• SDK v2 stable: 2026-07-28 (with the spec)
• SDK 1.x maintained (bug fixes + security) for ≥6 months after v2 stable — until at least ~end of Jan 2027
• Recommendation: let v2 stable bake for a few weeks post-release, target V3 for Sept–Oct 2026

Proposed V3 scope

• Swap to @modelcontextprotocol/server, drop @modelcontextprotocol/sdk
• registerTool() migration if not already done in 2.x (#260)
• Verify stdio transport under the stateless core against Claude Desktop / Claude Code / Cursor
• Re-cut the MCPB bundle + server.json against v2 (manifest sync from #255 carries over)
• Elicitation on the v2 inputRequired API (#261)
• Tasks extension for long-running deploys (#263)
• MCP Apps dashboard extension (#264)
• Bump major: npm 3.0.0

Child issues: #260 (annotations + registerTool, pre-V3), #261 (elicitation), #262 (structured output), #263 (Tasks extension), #264 (MCP Apps dashboard).

References

• Release candidate announcement: https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/
• 2026 roadmap: https://blog.modelcontextprotocol.io/posts/2026-mcp-roadmap/
• TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
• 2025-11-25 changelog (current stable spec): https://modelcontextprotocol.io/specification/2025-11-25/changelog

🤖 Generated with Claude Code