Major Release
TurboMCP v2.0.0: Progressive Enhancement & Clean Architecture
Complete architectural overhaul with minimal by default approach, clean code standards, and comprehensive security hardening for production deployments.
TurboMCP Engineering Team · · 22 min read
Release Overview
TurboMCP v2.0.0 represents a complete architectural overhaul focused on a clean minimal core with progressive enhancement. This major release eliminates technical debt, removes 2,900 lines of placeholder code, and establishes a foundation for sustainable long-term development.
After extensive pre-release security auditing and code quality review, we’ve achieved zero compiler warnings, zero clippy warnings, and reduced dependencies by 13 packages while maintaining complete MCP 2024-11-05 protocol compliance.
Key Achievements
- Progressive enhancement: Minimal by default (stdio only), opt-in features
- Clean code: Zero compiler/clippy warnings, minimal TODOs
- Security: 1 mitigated vulnerability, proper secret management
- Clean architecture: Authorization guidance (application-layer design)
- Latest toolchain: Rust 1.90.0 + 62 dependency updates
- Production ready: All examples compile, all tests pass, strict compliance
Progressive Enhancement Philosophy
The defining characteristic of v2.0 is the shift to progressive enhancement. Instead of including all features by default, TurboMCP 2.0 starts minimal and lets you opt in to exactly what you need.
Minimal by Default
A 60-second MCP server, with only the stdio transport included by default:
use turbomcp::prelude::*;
#[derive(Clone)]
struct Calculator;
#[server(name = "calculator", version = "2.0.0")]
impl Calculator {
#[tool("Add two numbers")]
async fn add(&self, a: f64, b: f64) -> McpResult<f64> {
Ok(a + b)
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
Calculator.run_stdio().await?;
Ok(())
}
// Cargo.toml - Minimal by default!
// [dependencies]
// turbomcp = "2.0" # Only stdio included
// tokio = { version = "1.0", features = ["full"] }
The default configuration includes only STDIO transport, which is perfect for Claude Desktop integration and CLI tools. Binary size is minimized, compilation is faster, and you only pay for what you use.
Opt-In Features
Progressive enhancement: add features as needed.
# Cargo.toml - Progressive enhancement
[dependencies]
turbomcp = { version = "2.0", features = [
"full", # All features
# Or opt-in selectively:
# "stdio", # STDIO transport (default)
# "http", # HTTP/SSE transport
# "websocket", # WebSocket transport
# "tcp", # TCP transport
# "auth", # OAuth 2.1 (turbomcp-auth)
# "dpop", # RFC 9449 DPoP (turbomcp-dpop)
] }
Feature selection strategy
- Start with minimal (stdio only) for development
- Add http or websocket for web integration
- Enable auth for OAuth 2.1 authentication
- Add dpop for RFC 9449 token binding security
- Use full for the comprehensive feature set
Clean Minimal Core
v2.0 represents a complete refactoring of core modules to eliminate monolithic files and improve maintainability. Two massive files were decomposed into focused, single-responsibility modules.
Module Decomposition
// BEFORE v2.0: Monolithic files
// turbomcp-core/src/context.rs: 2,046 lines
// turbomcp-protocol/src/types.rs: 2,888 lines
// AFTER v2.0: Focused modules
// Context module (8 modules):
turbomcp-core/src/context/
├── capabilities.rs # Capability trait definitions
├── client.rs # Client session and identification
├── completion.rs # Completion context handling
├── elicitation.rs # Interactive form handling
├── ping.rs # Health check contexts
├── request.rs # Core request/response context
├── server_initiated.rs # Server-initiated communication
└── templates.rs # Resource template contexts
// Protocol types (12 modules):
turbomcp-protocol/src/types/
├── capabilities.rs # Capability definitions
├── completion.rs # Completion types
├── content.rs # Content structures
├── core.rs # Core protocol types
├── domain.rs # Domain-specific types
├── elicitation.rs # Elicitation protocol
├── initialization.rs # Init messages
├── logging.rs # Logging types
├── ping.rs # Ping/health
├── prompts.rs # Prompt templates
├── requests.rs # Request structures
├── resources.rs # Resource handling
├── roots.rs # Filesystem roots
├── sampling.rs # LLM sampling
└── tools.rs # Tool definitions
| Before v2.0 | After v2.0 |
|---|---|
| context.rs: 2,046 lines | 8 context modules (~200 lines each) |
| types.rs: 2,888 lines | 12 protocol modules (~150 lines each) |
| Difficult to navigate | Clear separation of concerns |
| Merge conflicts frequent | Easy to navigate and modify |
| Hard to test individually | Testable in isolation |
Zero Compiler Warnings
Code quality metrics:
| Metric | Value |
|---|---|
| Compiler Warnings | 0 |
| Clippy Warnings | 0 |
| Dependencies | -13 |
Pre-Release Security Hardening
Before releasing v2.0, we conducted a comprehensive security audit and code quality review. This resulted in the removal of 2,900 lines of misleading placeholder code and implementation of proper secret management patterns.
Placeholder Code Removal
// Deleted 2,900 lines of fake LLM code from turbomcp-client
// BEFORE v2.0: Misleading placeholder code
// src/llm/openai.rs
pub struct OpenAIProvider {
// TODO: Implement OpenAI integration
// This is just a placeholder!
}
// src/llm/anthropic.rs
pub struct AnthropicProvider {
// TODO: Not actually implemented
}
// AFTER v2.0: Honest, production-ready
// ✅ Removed entire src/llm/ directory (2,818 lines)
// ✅ Removed fake provider implementations
// ✅ Clarified sampling protocol is infrastructure only
// ✅ LLM integration is user-implemented
// Result: Transparent, trustworthy codebase
Why this matters. Placeholder code creates false expectations and misleads users. v2.0 establishes an honest, production-ready codebase where every line of code is functional. The sampling protocol infrastructure is provided, but LLM integration is intentionally left to application developers.
Proper Secret Management
// BEFORE v2.0: Insecure defaults
impl Default for AuthConfig {
fn default() -> Self {
Self {
secret: "placeholder-secret".to_string(), // ❌ HARDCODED!
// ...
}
}
}
// AFTER v2.0: Forced explicit configuration
impl AuthConfig {
// ✅ Load from environment variables
pub fn from_env() -> Result<Self, ConfigError> {
Ok(Self {
secret: env::var("AUTH_SECRET")?,
issuer: env::var("AUTH_ISSUER")?,
// ...
})
}
}
// BEFORE v2.0: Dangerous CORS default
pub enum CorsOrigins {
Any, // ❌ Allows all origins
Mirror, // ❌ Unimplemented variant
// ...
}
// AFTER v2.0: Production-safe CORS
impl CorsConfig {
/// Production-safe CORS requiring explicit origins
pub fn production_safe() -> Self {
Self {
allowed_origins: vec![], // Must configure!
// Security warnings in docs for CorsOrigins::Any
}
}
}
New Crate Architecture
v2.0 introduces two new independent crates for authentication and security, allowing progressive adoption of security features without bloating the core SDK.
turbomcp-auth Crate (1,824 LOC)
Optional authentication crate for OAuth 2.0/2.1 support.
// New turbomcp-auth crate (1,824 LOC)
use turbomcp_auth::prelude::*;
// OAuth 2.1 with PKCE
let oauth_config = OAuth2Config::new()
.client_id("your-client-id")
.client_secret(env::var("CLIENT_SECRET")?)
.redirect_uri("http://localhost:8080/callback")
.authorization_endpoint("https://provider.com/authorize")
.token_endpoint("https://provider.com/token")
.with_pkce() // ✅ Enhanced security
.build();
// Multi-provider support
let google = OAuth2Provider::google(client_id, secret);
let github = OAuth2Provider::github(client_id, secret);
let microsoft = OAuth2Provider::microsoft(client_id, secret);
turbomcp-dpop Crate (7,160 LOC)
Optional DPoP crate for cryptographic token binding.
// New turbomcp-dpop crate (7,160 LOC)
use turbomcp_dpop::prelude::*;
// RFC 9449 DPoP token binding
let dpop_config = DpopConfig::new()
.algorithm(DpopAlgorithm::ES256) // P-256 (recommended)
.with_redis_store("redis://localhost")
.build();
// Generate cryptographically bound token
let dpop_proof = dpop_config
.generate_proof(
"https://api.example.com/resource",
"GET",
access_token
)
.await?;
// Multi-store support
enum DpopStore {
Memory, // Development
Redis, // Distributed production
HSM, // Maximum security (YubiHSM2, PKCS#11)
}
Performance Optimizations
Beyond architectural improvements, v2.0 includes significant performance optimizations through zero-copy message processing and enhanced SIMD acceleration.
- Zero-copy processing: Extensive
bytes::Bytesintegration for minimal allocations - Lazy deserialization: Messages deserialized only when needed
- SIMD acceleration:
sonic-rsandsimd-jsonfor 2-3x faster JSON - Optimized memory:
ZeroCopyMessagetype for ultra-high throughput
Migration from v1.x
Most v1.x applications will continue to work with minimal changes. The main breaking changes are related to default features and RBAC removal.
// Migration from v1.x to v2.0
// BREAKING CHANGE 1: Default features
// OLD (v1.x - everything enabled by default)
[dependencies]
turbomcp = "1.1" # All features included
// NEW (v2.0 - minimal by default)
[dependencies]
turbomcp = { version = "2.0", features = ["full"] }
// BREAKING CHANGE 2: RBAC removed (application-layer concern)
// OLD (v1.x - had RBAC feature)
turbomcp = { version = "1.1", features = ["rbac"] }
// NEW (v2.0 - implement in your application)
use turbomcp_server::middleware::auth::AuthMiddleware;
let auth = AuthMiddleware::new(|claims: &Claims| {
// Your authorization logic here
check_user_permissions(claims)
});
// BREAKING CHANGE 3: Feature gate naming
// OLD NEW
dpop-redis → redis-storage
dpop-test-utils → test-utils
// NO BREAKING CHANGES for:
// ✅ Existing macro API (#[server], #[tool], etc.)
// ✅ MCP protocol compliance
// ✅ Transport selection
// ✅ Core functionality
Backward compatible
The following features have zero breaking changes:
- Macro API (
#[server],#[tool],#[resource],#[prompt]) - MCP 2024-11-05 protocol compliance
- Transport selection and configuration
- Core functionality and APIs
- Existing auth, rate-limiting, validation features
What’s Next for TurboMCP
With the v2.0 foundation in place, we’re focused on:
- Enhanced documentation: Comprehensive guides for progressive enhancement patterns
- Production examples: Real-world deployment patterns and best practices
- Performance tuning: Further optimizations for high-throughput scenarios
- Community growth: Building an ecosystem of MCP servers and tools
Ready to Try TurboMCP v2.0?
Start building production-ready MCP servers with progressive enhancement and clean architecture. See the TurboMCP repository on GitHub, install from crates.io, or visit the TurboMCP product page.
Related articles:
- TurboMCP
- Architecture
- Security
- Clean Code
- Progressive Enhancement
- v2.0