TurboMCP Core

High-performance core abstractions and SIMD-accelerated message processing for the TurboMCP SDK.

Overview

turbomcp-core provides the foundational layer for TurboMCP, featuring performance-critical types and zero-copy optimization utilities. This crate serves as the foundation that enables TurboMCP's industry-leading performance characteristics.

Key Features

🚀 SIMD-Accelerated Processing

• 2-3x faster JSON parsing with simd-json and sonic-rs
• Vectorized operations for better CPU cache utilization
• SIMD-optimized message handling throughout the request lifecycle

📦 Zero-Copy Architecture

• Memory-efficient processing with Bytes-based message handling
• Minimal allocations through careful lifetime management
• SmallVec and CompactStr for optimized small data structures
• Lock-free data structures for high-concurrency scenarios
• Buffer pooling for reduced allocations
• Lazy JSON parsing for on-demand deserialization
• Memory-mapped file support for large data handling

🧵 Thread-Safe Session Management

• Concurrent session tracking with thread-safe state management
• LRU eviction policies with configurable memory limits
• Request correlation and distributed tracing support

🎯 Rich Error Handling

• Structured error types with full context using thiserror
• Error propagation with automatic conversion and context preservation
• Debugging support with detailed error information

📊 Observability Integration

• Built-in metrics hooks for performance monitoring
• Tracing integration points for distributed observability
• Request correlation IDs for end-to-end tracking

🎯 Enhanced Context Types (v1.0.3)

• ElicitationContext - Server-initiated user input requests with JSON schema validation
• CompletionContext - Intelligent autocompletion with reference tracking
• PingContext - Bidirectional health monitoring and keepalive
• ResourceTemplateContext - Dynamic resource generation with RFC 6570 templates
• BidirectionalContext - Support for server-initiated requests to clients

Architecture

┌─────────────────────────────────────────────┐
│                TurboMCP Core                │
├─────────────────────────────────────────────┤
│ SIMD Message Processing                     │
│ ├── simd-json acceleration                 │
│ ├── sonic-rs optimization                  │
│ └── Zero-copy Bytes handling               │
├─────────────────────────────────────────────┤
│ Session & Context Management               │
│ ├── RequestContext lifecycle              │
│ ├── Thread-safe session state             │
│ └── Correlation ID management             │
├─────────────────────────────────────────────┤
│ Error Handling & Observability            │
│ ├── Structured McpError types             │
│ ├── Context preservation                  │
│ └── Metrics & tracing hooks               │
└─────────────────────────────────────────────┘

Performance Characteristics

Benchmarks vs Standard Libraries

Optimization Features

• 🚀 SIMD Acceleration - CPU-level vectorized JSON processing
• 📦 Zero-Copy - Minimal memory allocations and copies
• 🔄 Efficient Collections - SmallVec, CompactStr for small data
• 🧵 Lock-Free Operations - Where possible for maximum concurrency

Usage

Basic Usage

use turbomcp_core::{RequestContext, Message, Context, McpResult};

// Create a request context for correlation and observability
let mut context = RequestContext::new();

// SIMD-accelerated message parsing happens automatically
let json_data = br#"{"jsonrpc": "2.0", "method": "tools/list"}"#;
let message = Message::parse_with_simd(json_data)?;

// Context provides rich observability and user information
context.info("Processing request").await?;

// Enhanced Context features (v1.0.3)
if context.is_authenticated() {
    let user = context.user().unwrap_or("unknown");
    let roles = context.roles();
    context.info(&format!("Authenticated user: {}, roles: {:?}", user, roles)).await?;
}

Advanced Session Management

use turbomcp_core::{SessionManager, SessionConfig};

// Configure session management with LRU eviction
let config = SessionConfig::new()
    .with_max_sessions(1000)
    .with_ttl_seconds(3600);

let session_manager = SessionManager::with_config(config);

// Sessions are automatically managed with efficient cleanup
let session = session_manager.create_session().await?;

Error Handling

use turbomcp_core::{McpError, McpResult};

fn process_request() -> McpResult<String> {
    // Rich error types with automatic context
    if invalid_input {
        return Err(McpError::InvalidInput(
            "Request missing required field".to_string()
        ));
    }
    
    // Errors automatically include correlation context
    Ok("processed".to_string())
}

SIMD Feature Flag

Enable maximum performance with SIMD acceleration:

[dependencies]
turbomcp-core = { version = "1.0.3", features = ["simd"] }

Note: SIMD features require compatible CPU architectures (x86_64 with AVX2 or ARM with NEON).

Feature Flags

Integration

With TurboMCP Framework

turbomcp-core is automatically included when using the main TurboMCP framework:

use turbomcp::prelude::*;

// Core functionality is available through the prelude
#[server]
impl MyServer {
    #[tool("Example with context")]
    async fn my_tool(&self, ctx: Context) -> McpResult<String> {
        // Context is powered by turbomcp-core
        ctx.info("Processing request").await?;
        Ok("result".to_string())
    }
}

Direct Usage

For custom implementations or integrations:

use turbomcp_core::{
    RequestContext, SessionManager, Message, McpError, McpResult
};

struct CustomHandler {
    sessions: SessionManager,
}

impl CustomHandler {
    async fn handle_request(&self, data: &[u8]) -> McpResult<String> {
        let context = RequestContext::new();
        let message = Message::parse_with_simd(data)?;
        
        // Use core functionality directly
        context.info("Custom processing").await?;
        Ok("processed".to_string())
    }
}

Error Types

Core error types for comprehensive error handling:

use turbomcp_core::McpError;

match result {
    Err(McpError::InvalidInput(msg)) => {
        // Handle validation errors
    },
    Err(McpError::SessionExpired(id)) => {
        // Handle session lifecycle
    },
    Err(McpError::Performance(details)) => {
        // Handle performance issues
    },
    Ok(value) => {
        // Process success case
    }
}

Development

Building

# Build with all features
cargo build --features simd,metrics,tracing

# Build optimized for production
cargo build --release --features simd

Testing

# Run comprehensive tests
cargo test

# Run performance benchmarks
cargo bench

# Test SIMD features (requires compatible CPU)
cargo test --features simd

Related Crates

• turbomcp - Main framework (uses this crate)
• turbomcp-protocol - MCP protocol implementation
• turbomcp-transport - Transport layer
• turbomcp-server - Server framework

License

Licensed under the MIT License.

Part of the TurboMCP high-performance Rust SDK for the Model Context Protocol.