Crate turbomcp_protocol

Expand description

§TurboMCP Protocol

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

§MCP Version Support

TurboMCP v3.0 fully implements MCP 2025-11-25 with all specification features enabled by default. No feature flags needed for core protocol capabilities.

Specification	Status	Notes
MCP 2025-11-25	✅ Full Support	Canonical v3 protocol surface

Quick Start:

turbomcp-protocol = "3.0"

Only the experimental Tasks API (SEP-1686) requires a feature flag:

turbomcp-protocol = { version = "3.0", features = ["experimental-tasks"] }

§What’s Inside

This crate provides everything needed for MCP:

Types: All MCP 2025-11-25 request/response types
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 (MCP 2025-11-25)

Complete MCP 2025-11-25 protocol implementation
JSON-RPC 2.0 support with batching and notifications
Type-safe capability negotiation and compatibility checking
Strict exact-version protocol negotiation
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

§MCP 2025-11-25 Features (Always Enabled)

All core MCP 2025-11-25 specification features are now always available:

Feature	SEP	Description
URL Elicitation	SEP-1036	URL mode for OAuth/sensitive data collection
Sampling Tools	SEP-1577	Tool calling in LLM sampling requests
Icons	SEP-973	Icon metadata for tools, resources, prompts
Enum Improvements	SEP-1330	Standards-based JSON Schema enum patterns

Experimental Feature (requires feature flag):

experimental-tasks - Tasks API (SEP-1686) for long-running operations

Authentication & Security (always enabled):

SSRF protection for URL validation
Client ID Metadata Documents (CIMD) for OAuth 2.1
OpenID Connect Discovery (RFC 8414 + OIDC 1.0)
Incremental consent with WWW-Authenticate (SEP-835)

§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

§Version Selection

TurboMCP v3.0 targets MCP 2025-11-25 only. Runtime negotiation is exact-match: clients and servers must agree on the current protocol version.

Typical Usage:

[dependencies]
turbomcp-protocol = "3.0"  # All core features included

With Experimental Tasks API:

[dependencies]
turbomcp-protocol = { version = "3.0", features = ["experimental-tasks"] }

§Runtime Version Negotiation

Clients and servers negotiate protocol versions during initialization:

use turbomcp_protocol::{InitializeRequest, InitializeResult, ClientCapabilities};
use turbomcp_protocol::types::{Implementation, ServerCapabilities}; // Corrected import path

// Client requests the current protocol version
let request = InitializeRequest {
    protocol_version: "2025-11-25".into(),  // Request draft
    capabilities: ClientCapabilities::default(),
    client_info: Implementation {
        name: "my-client".to_string(),
        title: None,
        version: "1.0.0".to_string(),
        ..Default::default()
    },
    _meta: None,
};

// Server responds with the same supported version
let response = InitializeResult {
    protocol_version: "2025-11-25".into(),
    capabilities: ServerCapabilities::default(),
    server_info: Implementation {
        name: "my-server".to_string(),
        title: None,
        version: "1.0.0".to_string(),
        ..Default::default()
    },
    instructions: None,
    _meta: None,
};

Key Principle: clients request the current protocol version, and servers must either accept it exactly or fail initialization.

§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,
            task: None,
            tools: None,
            tool_choice: 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::RichContextExt;
pub use context::ServerInitiatedContext;
pub use context::ServerInitiatedType;
pub use context::ServerToClientRequests;
pub use context::SessionStateGuard;
pub use context::StateError;
pub use context::TemplateParameter;
pub use context::active_sessions_count;
pub use context::cleanup_session_state;
pub use enhanced_registry::EnhancedRegistry;
pub use enhanced_registry::HandlerStats;
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::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;
pub use turbomcp_core as mcp_core;

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. Error handling types for MCP protocol.
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 constants
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 (single source of truth)
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
measure_time: Utility macro for measuring execution time
register_component: Macro for easier component registration

Structs§

Image: Wrapper for returning base64-encoded image data.
Json: Wrapper for returning JSON-serialized data from a tool handler.
McpError: Unified MCP error type
McpErrorContext: Additional error context
Text: Wrapper for explicitly returning text content.
ToolError: Error type for tool handlers that supports the ? operator.

Enums§

ErrorKind: Error classification for programmatic handling.

Constants§

DEFAULT_TIMEOUT_MS: Default timeout for operations in milliseconds
MAX_MESSAGE_SIZE: Maximum message size in bytes (1MB)
PROTOCOL_VERSION: MCP Protocol version supported by this SDK (latest official spec)
SDK_NAME: SDK name
SDK_VERSION: SDK version
SUPPORTED_VERSIONS: Supported protocol versions.

Traits§

IntoToolError: Convenience trait for converting to ToolError with context.
IntoToolResponse: Trait for types that can be converted into a tool response.

Type Aliases§

Error: v3.0 Error alias for migration (prefer McpError directly)
McpResult: Result type alias for MCP operations
Result: v3.0 Result alias using McpError