TurboMCP v1.0.5 Release Notes - 2025-09-09

🚀 Major Developer Experience Release

TurboMCP v1.0.5 focuses on delivering a world-class developer experience through comprehensive examples overhaul, simplified feature system, and enhanced error handling capabilities.

🎯 Major Examples Overhaul

Streamlined Learning Experience

• Reduced from 41 to 12 focused examples (70% reduction)
• Created clear learning progression from basics to production
• Added comprehensive EXAMPLES_GUIDE.md with learning path
• Fixed all compilation errors across examples
• Every example now works end-to-end without placeholders

New Architecture Examples

• 06_architecture_patterns.rs - Shows builder vs macro equivalence
• 06b_architecture_client.rs - Separate client for testing both patterns
• 07_transport_showcase.rs - Consolidated all transport demos
• 08_elicitation_complete.rs - Merged all elicitation patterns

Production-Ready HTTP Examples

• 08_elicitation_server.rs and 08_elicitation_client.rs - Real two-terminal HTTP testing
• Full MCP 2025-06-18 compliant HTTP/SSE transport with streaming capabilities
• Demonstrates configurable routes with /mcp endpoint

🚀 Developer Experience Improvements

📢 Simplified Feature System (Backwards Compatible)

DEPRECATED: internal-deps feature flag - Will be removed in 2.0.0

• Core framework dependencies now included automatically
• Migration: Remove internal-deps from feature lists for cleaner configuration
• Before: features = ["internal-deps", "stdio"] → After: features = ["minimal"] or features = ["stdio"]
• Backwards compatible: Old combinations work but show helpful deprecation warnings
• Rationale: Eliminates user confusion since these dependencies were always required

Enhanced Error Handling

NEW: McpErrorExt trait for ergonomic error conversion:

// Before: Verbose error handling
result.map_err(|e| McpError::Tool(format!("Failed: {}", e)))?

// After: Clean ergonomic methods
result.tool_error("Failed operation")?

Available Methods:

• .tool_error("context")? - Tool execution errors
• .network_error()? - Network/transport errors
• .protocol_error("context")? - MCP protocol violations
• .resource_error("context")? - Resource access errors
• .transport_error()? - Transport layer errors

Automatic From trait implementations for common error types:

• std::io::Error, reqwest::Error, chrono::ParseError, serde_json::Error, etc.

Improved Documentation & Discoverability

• Enhanced Prelude: use turbomcp::prelude::*; eliminates complex import chains
• 🎯 Feature Selection Guide: Comprehensive guidance in documentation and Cargo.toml
  • Clear recommendations for minimal vs full feature sets
  • Beginner-friendly guidance with specific use cases
  • Prominent placement of minimal features for basic tool servers
• 📚 Generated Methods Reference: Documents all #[server] macro-generated methods
  • Transport methods (run_stdio(), run_http(), run_tcp(), etc.)
  • Metadata and testing methods (server_info(), tool metadata functions)
  • Context injection behavior and flexible parameter positioning

✨ New Features

🎯 Complete MCP Protocol Support with New Attribute Macros

MAJOR FEATURE: TurboMCP now supports the entire MCP protocol

Four new attribute macros complete our MCP coverage, making TurboMCP the most comprehensive Rust MCP implementation:

#[completion] - Intelligent Autocompletion

#[completion("Complete file paths")]
async fn complete_path(&self, ctx: Context, partial: String) -> McpResult<Vec<String>> {
    ctx.info(&format!("Completing: {}", partial)).await?;
    Ok(vec!["config.json".to_string(), "data.txt".to_string()])
}

Features: Intelligent parameter suggestions, context-aware completions, real-time feedback

#[elicitation] - Structured User Input

#[elicitation("Collect user preferences")]
async fn get_preferences(&self, schema: serde_json::Value) -> McpResult<serde_json::Value> {
    // Server-initiated structured input collection with JSON schema validation
    Ok(serde_json::json!({"theme": "dark", "language": "en"}))
}

Features: Schema-validated input, server-initiated prompts, rich UI integration

#[ping] - Bidirectional Health Monitoring

#[ping("Health check")]
async fn health_check(&self) -> McpResult<String> {
    Ok("Server is healthy".to_string())
}

Features: Bidirectional health checks, connection monitoring, network diagnostics

#[template] - Resource Template Handlers

#[template("users/{user_id}/profile")]
async fn get_user_profile(&self, user_id: String) -> McpResult<String> {
    Ok(format!("Profile for user: {}", user_id))
}

Features: RFC 6570 URI templates, parameterized resources, dynamic content

🚀 Enhanced Client SDK with Completion Support

NEW in turbomcp-client: Native completion support

// Request completions from any server
let completions = client.complete("complete_path", "/usr/b").await?;
println!("Suggestions: {:?}", completions.values);

Test Coverage: 16 comprehensive completion tests validate functionality

Configurable HTTP Routes

• Enhanced /mcp endpoint with run_http_with_path() for custom paths
• Default /mcp route maintained for compatibility
• Flexible routing with into_router_with_path() for Axum integration
• Support for existing router state preservation

Advanced Axum Integration

• Production-grade integration layer for existing Axum applications
• State-preserving merge capabilities for "bring your own server" philosophy
• Zero-conflict route merging with existing stateful routers
• Tower service foundation for observability and error handling

MCP 2025-06-18 Compliance

• Streamable HTTP Transport: Full specification compliance with streaming capabilities
• Standard headers: Mcp-Session-Id (MCP standard) vs legacy headers
• Protocol version validation: Supports 2025-06-18, 2025-03-26, 2024-11-05
• Proper JSON-RPC handling: Returns 202 Accepted for notifications/responses per spec

Bidirectional Communication Support

Full support for all 4 MCP handler types:

• ElicitationHandler - Server-initiated prompts
• ProgressHandler - Operation tracking
• LogHandler - Structured logging
• ResourceUpdateHandler - File change notifications

🛠 Improvements

• Simplified API surface while maintaining full functionality
• Enhanced Cargo.toml: Reorganized feature flags with clear descriptions and recommendations
• Better error messages and compile-time validation
• Improved test coverage with real integration tests (800+ tests passing)
• Updated all dependencies to latest versions
• Enhanced documentation with clear examples and comprehensive method reference
• Ergonomic imports: Single prelude import provides everything needed for most use cases
• Production-ready error handling: Comprehensive error conversion utilities eliminate boilerplate

🐛 Bug Fixes

• Fixed schema generation in macro system
• Resolved handler registration issues
• Fixed transport lifecycle management
• Corrected async trait implementations

📚 Documentation

• Complete examples guide with difficulty ratings
• Learning path from "Hello World" to production
• Feature matrix showing which examples demonstrate what
• Clear explanation of builder vs macro trade-offs

🏗 Internal Changes

• Cleaned up legacy code and unused files
• Improved module organization
• Better separation of concerns
• Consistent error handling patterns

🔄 Migration Guide

Feature System Simplification

RECOMMENDED: Update your feature flags for cleaner configuration:

# Before (still works but shows deprecation warning)
turbomcp = { version = "1.0.5", features = ["internal-deps", "stdio"] }

# After (recommended)
turbomcp = { version = "1.0.5", features = ["minimal"] }
# OR
turbomcp = { version = "1.0.5", features = ["stdio"] }

Error Handling Enhancement

OPTIONAL: Leverage new ergonomic error handling:

// Before: Still works
result.map_err(|e| McpError::Tool(format!("Operation failed: {}", e)))?

// After: More ergonomic (recommended)  
result.tool_error("Operation failed")?

Import Simplification

RECOMMENDED: Use prelude for cleaner imports:

// Before: Multiple specific imports
use turbomcp::{Server, Context, McpResult, McpError, /* ... */};

// After: Single prelude import
use turbomcp::prelude::*;

New Macro Usage

NEW: Leverage the new attribute macros for complete MCP coverage:

#[server]
impl MyServer {
    #[tool("Execute task")]
    async fn execute(&self, task: String) -> McpResult<String> { ... }
    
    #[completion("Complete task names")]  // NEW in 1.0.5
    async fn complete_task(&self, partial: String) -> McpResult<Vec<String>> { ... }
    
    #[elicitation("Configure settings")]  // NEW in 1.0.5
    async fn configure(&self, ctx: Context) -> McpResult<serde_json::Value> { ... }
    
    #[ping("Health check")]  // NEW in 1.0.5
    async fn ping(&self) -> McpResult<String> { ... }
    
    #[template("files/{path}")]  // NEW in 1.0.5
    async fn get_file(&self, path: String) -> McpResult<String> { ... }
}

🎯 Feature Recommendations

For Basic Tool Servers

turbomcp = { version = "1.0.5", features = ["minimal"] }

Perfect for: CLI integrations, simple MCP tools, getting started

For Production Web Servers

turbomcp = "1.0.5"  # Uses full feature set by default

Perfect for: Production deployments, web applications, enterprise usage

Custom Feature Selection

turbomcp = { 
    version = "1.0.5", 
    default-features = false, 
    features = ["minimal", "http", "schema-generation"] 
}

Perfect for: Tailored deployments with specific transport needs

📈 Release Statistics

• 🎯 70% reduction in example count (41 → 12) for focused learning
• 🚀 4 NEW ATTRIBUTE MACROS completing MCP protocol coverage (#[completion], #[elicitation], #[ping], #[template])
• ✨ Enhanced client SDK with complete() method and 16 comprehensive tests
• 🌐 5 major DX improvements addressing real user feedback
• 🛠 Advanced transport features including configurable HTTP routes and Axum integration
• 📋 Comprehensive elicitation system with 8 integration tests validating real functionality
• 🐛 4 critical bug fixes in core systems
• 📚 Complete documentation overhaul with learning paths and method references
• 🏗 4 internal improvements for maintainability and performance

🎉 What's Next

Future releases will focus on:

• v1.0.6: Client architecture enhancements and plugin system
• Performance optimizations and SIMD acceleration features
• Advanced tooling and development utilities