TurboMCP 2.0.0 Release Notes

TL;DR

TurboMCP 2.0.0 is a complete architectural overhaul focused on:

• ✅ MCP 2025-06-18 Full Compliance across all transports
• ✅ Progressive Enhancement - minimal by default, opt-in features
• ✅ Zero Technical Debt - no warnings, no TODOs, production-ready
• ✅ Enhanced Developer Experience - rich tool metadata, better errors
• ⚠️ Breaking Changes - see migration guide below

🌟 What's New in 2.0.0 Final

Rich Tool Descriptions (New in Final)

#[tool(
    description = "Search files in workspace",
    usage = "Use when user asks about file contents or code structure",
    performance = "Fast for <10k files, slower for larger workspaces",
    related = ["list_files", "read_file"],
    examples = ["search pattern:TODO", "search path:src/ pattern:async"]
)]

• Impact: Better LLM decision-making with contextual metadata
• Backward Compatible: Simple string syntax still works

STDIO Transport MCP Compliance

• Strict Validation: Rejects embedded newlines (LF/CR/CRLF) per MCP spec
• Better Errors: MCP-specific compliance messages
• Production Safe: Prevents message framing issues

🚨 Breaking Changes (from 1.x → 2.0)

1. RBAC Removed (Architectural Decision)

Why: Authorization is application-layer concern, not protocol-layer
Migration: Implement in your app using JWT claims or external policy engine
Benefit: Cleaner architecture, removed unmaintained dependency

// ❌ OLD (no longer works)
turbomcp-server = { features = ["rbac"] }

// ✅ NEW (implement in your application)
// See examples/custom_auth.rs for patterns

2. Default Features Changed to Minimal

Why: Progressive enhancement - users opt-in to what they need
Migration: Explicitly enable features

# ❌ OLD (1.x - everything enabled)
turbomcp = "1.x"

# ✅ NEW (minimal by default)
turbomcp = { version = "2.0", features = ["stdio"] }

# OR use full bundle
turbomcp = { version = "2.0", features = ["full"] }

3. SharedClient Removed

Why: Client<T> is now Arc-wrapped internally
Migration: Use .clone() directly instead of SharedClient::new()

// ❌ OLD
let shared = SharedClient::new(client);

// ✅ NEW
let cloned = client.clone(); // Client is already Arc-wrapped

🏗️ Major Architecture Changes

All Transports Now Unified & MCP Compliant

Critical Fix: Eliminated implementation drift between macro and builder patterns

• Before: ~2,200 lines of duplicate transport code
• After: Single source of truth - all use turbomcp-server runtime
• Impact: Full MCP compliance guaranteed across STDIO/TCP/Unix/HTTP/WebSocket

HTTP & WebSocket Bidirectional Support

• ✅ HTTP/SSE: Full elicitation, sampling, roots, ping support
• ✅ WebSocket: Complete bidirectional matching macro pattern
• ✅ Factory Patterns: Per-connection/per-session dispatchers

Critical Bug Fixes (from RC.2)

Sampling Request ID Correlation (CRITICAL)

• Problem: Clients couldn't correlate rejections with server requests
• Fix: Added request_id parameter to SamplingHandler trait
• Result: User rejections complete instantly (was 60s timeout)

WebSocket Deadlock (P0)

• Problem: Requests timed out after 60 seconds
• Fix: Spawn handlers in separate tasks (non-blocking receive loop)
• Result: Response time: 60s → 0ms

HTTP Session ID Generation

• Problem: Server rejecting SSE connections without session ID
• Fix: Server generates and sends session ID per MCP spec
• Result: HTTP sampling/elicitation now works correctly

✨ New Features & Improvements

Enhanced Developer Experience

• Better Error Messages: JSON-RPC error codes now semantically correct
• Schema Builders: Comprehensive functions for elicitation API
• Test Coverage: 1,165+ tests passing
• Zero Warnings: Strict clippy compliance with -D warnings

Performance Optimizations

• Zero-copy message processing with bytes::Bytes
• SIMD-accelerated JSON with sonic-rs and simd-json
• Lazy deserialization and minimal allocations

Security Enhancements (only relevant for auth and dpop users)

• Removed: instant unmaintained dependency (RUSTSEC-2024-0384)
• Only 1 Vulnerability: RSA timing (mitigated - use P-256 instead)
• Only 1 Warning: paste v1.0.15 (compile-time only, zero runtime risk)

📦 Migration Guide (1.x → 2.0)

Quick Migration Checklist

1. Update Cargo.toml

[dependencies]
turbomcp = { version = "2.0", features = ["full"] }

1. Remove RBAC (if used)

   • Implement authorization in application layer
   • See RBAC-REMOVAL-SUMMARY.md for patterns

2. Update SharedClient (if used)

// Replace SharedClient::new(client)
client.clone()  // Client is already Arc-wrapped

1. Update Feature Names

# OLD feature names
dpop-redis → redis-storage
dpop-test-utils → test-utils

1. Update SamplingHandler (if implemented)

// Add request_id parameter
async fn handle(
    &self,
    request_id: String,  // NEW - required
    request: SamplingRequest
) -> Result<SamplingResponse>

📊 Quality Metrics

Codebase Quality:

• ✅ Compiler warnings: 0
• ✅ Clippy warnings: 0 (with -D warnings)
• ✅ Technical debt markers: 0 (no TODO/FIXME)
• ✅ Test suite: 1,165+ tests passing
• ✅ All examples compile and run

Security Posture:

• 🔒 Known vulnerabilities: 1 (mitigated via P-256 recommendation)
• ⚠️ Unmaintained deps: 1 (compile-time only, zero runtime risk)
• ✅ Security improvements: Removed runtime unmaintained dependencies

Dependency Management:

• 📦 Feature-gated: Pay only for what you use
• 📉 -13 dependencies from 1.x (-2.2%)
• 📈 +62 dependency updates to latest versions
• 🦀 Rust 1.90.0 (latest stable)

🎯 MCP 2025-06-18 Compliance

Full compliance verified:

• ✅ STDIO Transport: Newline-delimited JSON, no embedded newlines
• ✅ HTTP/SSE Transport: Proper session management, bidirectional
• ✅ WebSocket Transport: Full bidirectional, no deadlocks
• ✅ TCP/Unix Transports: MCP-compliant custom extensions
• ✅ All Protocol Methods: initialize, tools, resources, prompts, sampling, elicitation, completion, roots, ping

🔗 Resources

• Documentation: https://turbomcp.org
• Repository: https://github.com/Epistates/turbomcp
• Migration Guide: See MIGRATION.md in repo
• RBAC Migration: See RBAC-REMOVAL-SUMMARY.md in repo
• Changelog: See CHANGELOG.md for complete details
• Examples: 18 production-ready examples in crates/turbomcp/examples/

🙏 Acknowledgments

Special thanks to all contributors and early adopters who provided feedback during the RC phase. Your input shaped this release.

📅 Release Timeline

• v2.0.0-rc (Oct 9, 2025) - Initial overhaul
• v2.0.0-rc.1 (Oct 11, 2025) - Transport fixes
• v2.0.0-rc.2 (Oct 16, 2025) - Critical bug fixes
• v2.0.0-rc.3 (Oct 18, 2025) - Final polish
• v2.0.0 (Oct 18, 2025) - Production release ✅

🚀 Getting Started

# Create a new project
cargo new my-mcp-server
cd my-mcp-server

# Add TurboMCP
cargo add turbomcp --features full

# For examples:
git clone https://github.com/Epistates/turbomcp.git

# And run an example
cargo run --example minimal_server

# Or start with the tutorial
cargo run --example 01_hello_world

Next Steps:

1. Read the Quick Start Guide
2. Explore 18 examples
3. Join Discord community for support

🎉 Happy Building with TurboMCP 2.0!