Crate turbomcp_server 

TurboMCP Server

MCP (Model Context Protocol) server implementation with graceful shutdown, routing, lifecycle management, and comprehensive observability features.

Features

• Roots Configuration - Configurable filesystem roots via builder API or macro
• Elicitation Support - Server-initiated requests for interactive user input
• Sampling Protocol - Bidirectional LLM sampling with client interaction
• Graceful Shutdown - Shutdown handling with signal support
• Multi-Transport - STDIO, TCP, Unix, WebSocket, HTTP/SSE support
• Middleware Stack - Authentication, rate limiting, and security headers
• Request Routing - Efficient handler registration and dispatch
• Health Monitoring - Comprehensive health checks and metrics
• Error Recovery - Robust error handling and recovery mechanisms
• MCP Compliance - Full support for tools, prompts, resources, roots, sampling, and elicitation
• Server-Initiated Requests - Support for sampling and elicitation via ServerCapabilities

Example

use turbomcp_server::ServerBuilder;
use turbomcp_protocol::types::Root;
use tokio::signal;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = ServerBuilder::new()
        .name("MyServer")
        .version("1.0.0")
        // Configure filesystem roots
        .root("file:///workspace", Some("Workspace".to_string()))
        .root("file:///tmp", Some("Temp".to_string()))
        .build();
     
    // Get shutdown handle for graceful termination
    let shutdown_handle = server.shutdown_handle();
     
    // In production: spawn server and wait for shutdown
    // tokio::spawn(async move { server.run_stdio().await });
    // signal::ctrl_c().await?;
    // shutdown_handle.shutdown().await;
     
    Ok(())
}

Elicitation Support

The server includes comprehensive elicitation support for interactive user input:

• ElicitationCoordinator for managing elicitation lifecycle
• Request/response correlation with timeouts
• Retry logic with configurable attempts
• Priority-based request queuing
• Automatic cleanup of expired requests

Sampling Support

The server provides built-in support for server-initiated sampling requests to clients:

use turbomcp_server::sampling::SamplingExt;
use turbomcp_protocol::RequestContext;
use turbomcp_protocol::types::{CreateMessageRequest, SamplingMessage, Role, Content, TextContent};

async fn my_tool(ctx: RequestContext) -> Result<String, Box<dyn std::error::Error>> {
    // Create a sampling request
    let request = CreateMessageRequest {
        messages: vec![SamplingMessage {
            role: Role::User,
            content: Content::Text(TextContent {
                text: "What is 2+2?".to_string(),
                annotations: None,
                meta: None,
            }),
            metadata: None,
        }],
        max_tokens: 50,
        model_preferences: None,
        system_prompt: Some("You are a helpful math assistant.".to_string()),
        include_context: Some(turbomcp_protocol::types::IncludeContext::None),
        temperature: Some(0.7),
        stop_sequences: None,
        _meta: None,
    };

    // Send the request to the client
    let result = ctx.create_message(request).await?;
    Ok(format!("Response: {:?}", result))
}

Sampling Features:

• Client-side sampling configuration support
• Server-side sampling metadata tracking
• Integration with elicitation for dynamic sampling decisions
• Configurable timeouts and retry logic

Compile-Time Routing (Experimental)

Zero-cost compile-time router generation for high-throughput scenarios:

• Zero-cost compile-time router generation
• Type-safe route matching at compile time
• Automatic handler registration through macros
• Performance optimization for high-throughput scenarios

Note: Compile-time routing is experimental and may have limitations with some MCP protocol methods.

Re-exports

pub use config::Configuration;

pub use config::ConfigurationBuilder;

pub use config::ServerConfig;

pub use error::ServerError;

pub use error::ServerResult;

pub use handlers::CompletionHandler;

pub use handlers::ElicitationHandler;

pub use handlers::LoggingHandler;

pub use handlers::PingHandler;

pub use handlers::PromptHandler;

pub use handlers::ResourceHandler;

pub use handlers::ResourceTemplateHandler;

pub use handlers::SamplingHandler;

pub use handlers::ToolHandler;

pub use lifecycle::HealthStatus;

pub use lifecycle::ServerLifecycle;

pub use lifecycle::ShutdownSignal;

pub use metrics::MetricsCollector;

pub use metrics::ServerMetrics;

pub use observability::ObservabilityConfig;

pub use observability::ObservabilityGuard;

pub use observability::OtlpProtocol;

pub use observability::PerformanceMonitor;

pub use observability::SamplingConfig;

pub use observability::SecurityAuditLogger;

pub use observability::global_observability;

pub use registry::HandlerRegistry;

pub use registry::Registry;

pub use registry::RegistryBuilder;

pub use routing::RequestRouter;

pub use routing::Route;

pub use routing::Router;

pub use server::McpServer;

pub use server::ServerBuilder;

pub use server::ShutdownHandle;

pub use elicitation::ElicitationCoordinator;

pub use elicitation::ElicitationTransport;

pub use elicitation::SharedElicitationCoordinator;

Modules

capabilities

Server-to-client request adapter for bidirectional MCP communication.

config

Server configuration management

elicitation

Elicitation support for TurboMCP servers

error

Server error types and handling

error_sanitization

Error Message Sanitization (Sprint 3.1)

handler_validation

Secure Handler Name Validation

handlers

Handler traits and implementations for MCP operations

lifecycle

Server lifecycle management and graceful shutdown

metrics

Production-grade metrics collection and monitoring system

observability

Production-grade OpenTelemetry observability integration

prelude

Prelude for common server functionality

registry

Server-side handler registry for MCP protocol implementation.

routing

Request routing and handler dispatch system

runtime

Runtime components for bidirectional transport

sampling

Server-initiated sampling support for TurboMCP

security_checks

Runtime Security Checks (Sprint 2.6)

server

MCP server core implementation

service

Core MCP service implementation using Tower pattern

timeout

Tool timeout and cancellation management

Macros

instrument_async

Helper macro for instrumenting async functions

measure_performance

Helper macro for performance span measurement

Structs

CallToolRequest

A request to execute a specific tool.

CallToolResult

The result of a CallToolRequest.

ClientCapabilities

Client capabilities per MCP 2025-06-18 specification

JsonRpcError

JSON-RPC error object

JsonRpcRequest

JSON-RPC request message

JsonRpcResponse

JSON-RPC response message

JsonRpcVersion

JSON-RPC version type

ListToolsResult

The result of a ListToolsRequest.

RequestContext

Context information for a single MCP request, carried through its entire lifecycle.

ServerCapabilities

Server capabilities per MCP 2025-06-18 specification

Tool

Represents a tool that can be executed by an MCP server, as per the MCP 2025-06-18 specification.

Enums

MessageId

Unique identifier for messages

Constants

SERVER_NAME

Server name

SERVER_VERSION

Server version

Functions

default_config

Default server configuration

server

Create a new server builder