Crate turbomcp_core 

TurboMCP Core

Foundation crate for the Model Context Protocol (MCP) SDK providing core types, error handling, and optimized abstractions for building MCP applications.

Features

• SIMD-Accelerated JSON - Fast processing with simd-json and sonic-rs
• Rich Error Handling - Comprehensive error types with context information
• Session Management - Configurable LRU eviction and lifecycle management
• Zero-Copy Processing - Memory-efficient message handling with Bytes
• Request Context - Full request/response context tracking for observability
• Server Capabilities - Support for server-initiated requests (sampling, elicitation)
• Performance Optimized - Memory-bounded state management with cleanup tasks
• Observability Ready - Built-in support for tracing and metrics collection

Architecture

turbomcp-core/
├── error/          # Error types and handling
├── message/        # Message types and serialization
├── types/          # Core protocol types
├── context/        # Request/response context with server capabilities
├── session/        # Session management
├── registry/       # Component registry
├── state/          # State management
└── utils/          # Utility functions

Server Capabilities

The core provides a ServerCapabilities trait that enables server-initiated requests to clients, supporting bidirectional communication patterns like sampling and elicitation:

use turbomcp_core::{RequestContext, ServerCapabilities};

// Tools can access server capabilities through the context
async fn my_tool(ctx: RequestContext) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    if let Some(capabilities) = ctx.server_capabilities() {
        // Make a sampling request to the client
        let request = serde_json::json!({
            "messages": [{"role": "user", "content": "Hello"}],
            "max_tokens": 100
        });
        let response = capabilities.create_message(request).await?;
    }
    Ok(())
}

Usage

This crate provides the foundation types and utilities used by other TurboMCP crates. It is typically not used directly but imported by the main turbomcp SDK.

Re-exports

pub use context::BidirectionalContext;

pub use context::ClientCapabilities;

pub use context::ClientId;

pub use context::ClientIdExtractor;

pub use context::ClientSession;

pub use context::CommunicationDirection;

pub use context::CommunicationInitiator;

pub use context::CompletionCapabilities;

pub use context::CompletionContext;

pub use context::CompletionOption;

pub use context::CompletionReference;

pub use context::ConnectionMetrics;

pub use context::ElicitationContext;

pub use context::ElicitationState;

pub use context::PingContext;

pub use context::PingOrigin;

pub use context::RequestContext;

pub use context::RequestContextExt;

pub use context::RequestInfo;

pub use context::ResourceTemplateContext;

pub use context::ResponseContext;

pub use context::ServerCapabilities;

pub use context::ServerInitiatedContext;

pub use context::ServerInitiatedType;

pub use context::TemplateParameter;

pub use enhanced_registry::EnhancedRegistry;

pub use enhanced_registry::HandlerStats;

pub use error::Error;

pub use error::ErrorKind;

pub use error::Result;

pub use handlers::CompletionItem;

pub use handlers::CompletionProvider;

pub use handlers::ElicitationHandler;

pub use handlers::ElicitationResponse;

pub use handlers::HandlerCapabilities;

pub use handlers::PingHandler;

pub use handlers::PingResponse;

pub use handlers::ResolvedResource;

pub use handlers::ResourceTemplate;

pub use handlers::ResourceTemplateHandler;

pub use handlers::ServerInitiatedCapabilities;

pub use handlers::TemplateParam;

pub use message::Message;

pub use message::MessageId;

pub use message::MessageMetadata;

pub use session::SessionAnalytics;

pub use session::SessionConfig;

pub use session::SessionManager;

pub use state::StateManager;

pub use types::ContentType;

pub use types::ProtocolVersion;

pub use types::Timestamp;

Modules

context

Request and response context for rich metadata handling.

enhanced_registry

Enhanced registry with support for MCP protocol handlers

error

Comprehensive error handling with rich context preservation.

error_utils

Error handling utility functions for consistent error patterns

handlers

Handler traits for extensible MCP protocol support

lock_free

Lock-free data structures for high-performance concurrent access

message

Optimized message types and serialization.

registry

Component registry system for extensible architecture.

session

Session management for TurboMCP applications

state

State management utilities for MCP servers

types

Core protocol types and data structures.

utils

Utility functions and helper macros.

zero_copy

Zero-copy message processing for ultra-high performance

Macros

feature_gate

Utility macro for conditional compilation based on features

mcp_error

Convenience macro for creating errors with context

measure_time

Utility macro for measuring execution time

register_component

Macro for easier component registration

Constants

DEFAULT_TIMEOUT_MS

Default timeout for operations in milliseconds

MAX_MESSAGE_SIZE

Maximum message size in bytes (16MB)

PROTOCOL_VERSION

Current MCP protocol version supported by this SDK

SDK_NAME

SDK name identifier

SDK_VERSION

SDK version information

SUPPORTED_VERSIONS

Supported protocol versions for compatibility

Type Aliases

Context

Alias for RequestContext for backward compatibility