Crate turbomcp_protocol 

TurboMCP Protocol

Complete Model Context Protocol (MCP) implementation in Rust, providing all protocol types, traits, context management, and message handling for building MCP applications.

What’s Inside

This crate provides everything needed for MCP:

• Types: All MCP request/response types from the MCP 2025-06-18 specification
• Traits: ServerToClientRequests for bidirectional communication
• Context: Request and response context management with full observability
• JSON-RPC: JSON-RPC 2.0 implementation with batching and notifications
• Validation: JSON Schema validation with comprehensive constraints
• Error Handling: Rich error types with context and tracing
• Message Handling: Optimized message processing with zero-copy support
• Session Management: Configurable LRU eviction and lifecycle management
• Zero-Copy: Optional zero-copy optimizations for high performance

Features

Core Protocol Support

• Complete MCP 2025-06-18 protocol implementation
• JSON-RPC 2.0 support with batching and notifications
• Type-safe capability negotiation and compatibility checking
• Protocol versioning with backward compatibility
• Fast serialization with SIMD acceleration

Advanced Protocol Features

• Elicitation Protocol - Server-initiated user input requests with rich schema validation
• Sampling Support - Bidirectional LLM sampling with fully-typed interfaces
• Roots Protocol - Filesystem boundaries with roots/list support
• Server-to-Client Requests - Fully typed trait for sampling, elicitation, and roots
• Comprehensive Schema Builders - Type-safe builders for all schema types

Performance & Observability

• SIMD-Accelerated JSON - Fast processing with simd-json and sonic-rs
• Zero-Copy Processing - Memory-efficient message handling with Bytes
• Request Context - Full request/response context tracking for observability
• Session Management - Memory-bounded state management with cleanup tasks
• Observability Ready - Built-in support for tracing and metrics collection

Migration from v1.x

In v2.0.0, turbomcp-core was merged into turbomcp-protocol to eliminate circular dependencies and enable fully-typed bidirectional communication.

// v1.x
use turbomcp_protocol::{RequestContext, Error};
use turbomcp_protocol::types::CreateMessageRequest;

// v2.0.0
use turbomcp_protocol::{RequestContext, Error, types::CreateMessageRequest};

All functionality is preserved, just the import path changed!

Architecture

turbomcp-protocol/
├── error/              # Error types and handling
├── message/            # Message types and serialization
├── context/            # Request/response context with server capabilities
├── types/              # MCP protocol types
├── jsonrpc/            # JSON-RPC 2.0 implementation
├── validation/         # Schema validation
├── session/            # Session management
├── registry/           # Component registry
└── utils/              # Utility functions

Server-to-Client Communication

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

use turbomcp_protocol::{RequestContext, types::CreateMessageRequest, ServerToClientRequests};

// 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.clone().server_to_client() {
        // Make a fully-typed sampling request to the client
        let request = CreateMessageRequest {
            messages: vec![/* ... */],
            max_tokens: 100,
            model_preferences: None,
            system_prompt: None,
            include_context: None,
            temperature: None,
            stop_sequences: None,
            _meta: None,
        };
        let response = capabilities.create_message(request, ctx).await?;
    }
    Ok(())
}

Re-exports

pub use context::BidirectionalContext;

pub use context::ClientCapabilities as ContextClientCapabilities;

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 as ContextCompletionReference;

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::ServerInitiatedContext;

pub use context::ServerInitiatedType;

pub use context::ServerToClientRequests;

pub use context::TemplateParameter;

pub use enhanced_registry::EnhancedRegistry;

pub use enhanced_registry::HandlerStats;

pub use error::Error;

pub use error::ErrorContext;

pub use error::ErrorKind;

pub use error::Result;

pub use error::RetryInfo;

pub use handlers::CompletionItem;

pub use handlers::CompletionProvider;

pub use handlers::ElicitationHandler;

pub use handlers::ElicitationResponse;

pub use handlers::HandlerCapabilities;

pub use handlers::JsonRpcHandler;

pub use handlers::PingHandler;

pub use handlers::PingResponse;

pub use handlers::ResolvedResource;

pub use handlers::ResourceTemplate as HandlerResourceTemplate;

pub use handlers::ResourceTemplateHandler;

pub use handlers::ServerInfo;

pub use handlers::ServerInitiatedCapabilities;

pub use handlers::TemplateParam;

pub use message::Message;

pub use message::MessageId;

pub use message::MessageMetadata;

pub use registry::RegistryError;

pub use security::validate_file_extension;

pub use security::validate_path;

pub use security::validate_path_within;

pub use session::SessionAnalytics;

pub use session::SessionConfig;

pub use session::SessionManager;

pub use shared::ConsumableShared;

pub use shared::Shareable;

pub use shared::Shared;

pub use shared::SharedError;

pub use state::StateManager;

pub use types::CallToolRequest;

pub use types::CallToolResult;

pub use types::ClientCapabilities;

pub use types::GetPromptRequest;

pub use types::GetPromptResult;

pub use types::InitializeRequest;

pub use types::InitializeResult;

pub use types::ReadResourceRequest;

pub use types::ReadResourceResult;

pub use types::ServerCapabilities;

pub use jsonrpc::JsonRpcBatch;

pub use jsonrpc::JsonRpcError;

pub use jsonrpc::JsonRpcErrorCode;

pub use jsonrpc::JsonRpcNotification;

pub use jsonrpc::JsonRpcRequest;

pub use jsonrpc::JsonRpcResponse;

pub use jsonrpc::JsonRpcVersion;

pub use capabilities::CapabilityMatcher;

pub use capabilities::CapabilityNegotiator;

pub use capabilities::CapabilitySet;

pub use capabilities::builders::ClientCapabilitiesBuilder;

pub use capabilities::builders::ClientCapabilitiesBuilderState;

pub use capabilities::builders::ServerCapabilitiesBuilder;

pub use capabilities::builders::ServerCapabilitiesBuilderState;

pub use versioning::VersionCompatibility;

pub use versioning::VersionManager;

pub use versioning::VersionRequirement;

Modules

capabilities

Capability negotiation and management.

config

Configuration for protocol components. Configuration types and utilities for MCP core

context

Request/response context, including server-to-client capabilities. Context module for MCP request and response handling.

enhanced_registry

An advanced handler registry with metrics and enhanced features. Advanced registry with MCP protocol handler support and observability.

error

Error types and handling for the protocol. Comprehensive error handling with rich context preservation.

error_codes

Protocol error codes (JSON-RPC standard + MCP extensions)

error_utils

Utilities for creating and working with protocol errors. Error handling utility functions for consistent error patterns

features

Protocol feature flags

handlers

Traits and types for handling different MCP requests (tools, prompts, etc.). Handler traits for extensible MCP protocol support

jsonrpc

JSON-RPC 2.0 protocol implementation.

message

Core message types and serialization logic. Optimized message types and serialization.

methods

Protocol method names

registry

Basic handler registration and lookup. Generic component registry for dependency injection and service location.

security

Security-related utilities, such as path validation. Security utilities for TurboMCP

session

Session management for client connections. Session management for TurboMCP applications

shared

Utilities for shared, concurrent state management. Generic shared wrapper traits and utilities

state

State management for the protocol. State management utilities for MCP servers

test_helpers

Public test utilities for use in downstream crates. Test utilities for turbomcp-protocol

types

All MCP protocol types (requests, responses, and data structures). MCP Protocol Types Module

utils

General utility functions. Utility functions and helper macros.

validation

Schema validation for protocol messages.

versioning

Protocol version management and compatibility checking.

zero_copy

Zero-copy data handling utilities for performance-critical operations. Zero-copy message processing with minimal allocations

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 (1MB) - Reduced for security (DoS protection)

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