Crate turbomcp_core

Expand description

§TurboMCP Core

Core MCP types and primitives - no_std compatible for WASM targets.

This crate provides the foundational types for the Model Context Protocol (MCP) that can be used in no_std environments including WebAssembly.

§Features

std (default): Enable standard library support, including richer error types
rich-errors: Enable UUID-based error tracking (requires std)
wasm: Enable WASM-specific optimizations
zero-copy: Enable rkyv zero-copy serialization for internal message passing

§Unified Handler Trait

The McpHandler trait is the core abstraction for MCP servers. It works on both native and WASM targets through platform-adaptive bounds:

use turbomcp_core::{McpHandler, RequestContext};
use turbomcp_types::*;

#[derive(Clone)]
struct MyServer;

impl McpHandler for MyServer {
    fn server_info(&self) -> ServerInfo {
        ServerInfo::new("my-server", "1.0.0")
    }
    // ... other methods
}

§Platform-Adaptive Bounds

The MaybeSend and MaybeSync marker traits enable unified code:

Native: Requires Send + Sync for multi-threaded executors
WASM: No thread safety requirements (single-threaded)

§no_std Usage

[dependencies]
turbomcp-core = { version = "3.6.0", default-features = false }

§Module Organization

auth: Authentication traits and types (portable across native/WASM)
handler: Unified MCP handler trait
context: Request context types
marker: Platform-adaptive marker traits
error: Error types and handling
jsonrpc: JSON-RPC 2.0 types

MCP protocol types (tools, resources, prompts, capabilities, etc.) live in turbomcp_types and are re-exported from this crate’s root.

§Example

use turbomcp_core::{Tool, ToolInputSchema};
use turbomcp_core::error::{McpError, ErrorKind};

// Create a tool definition
let tool = Tool {
    name: "calculator".into(),
    description: Some("Performs calculations".into()),
    input_schema: ToolInputSchema::default(),
    ..Default::default()
};

Re-exports§

pub use error::ErrorKind;
pub use error::McpError;
pub use error::McpResult;
pub use jsonrpc::JSONRPC_VERSION;
pub use jsonrpc::JsonRpcError;
pub use jsonrpc::JsonRpcErrorCode;
pub use jsonrpc::JsonRpcIncoming;
pub use jsonrpc::JsonRpcNotification;
pub use jsonrpc::JsonRpcOutgoing;
pub use jsonrpc::JsonRpcRequest;
pub use jsonrpc::JsonRpcResponse;
pub use jsonrpc::JsonRpcVersion;
pub use jsonrpc::RequestId;
pub use jsonrpc::ResponseId;
pub use response::Image;
pub use response::IntoToolError;
pub use response::IntoToolResponse;
pub use response::Json;
pub use response::Text;
pub use response::ToolError;
pub use security::DANGEROUS_URI_SCHEMES;
pub use security::DEFAULT_MAX_STRING_LENGTH;
pub use security::DEFAULT_MAX_URI_LENGTH;
pub use security::InputLimits;
pub use security::InputValidationError;
pub use security::check_uri_scheme_safety;
pub use security::sanitize_error_message;
pub use auth::AuthError;
pub use auth::Authenticator;
pub use auth::Credential;
pub use auth::CredentialExtractor;
pub use auth::HeaderExtractor;
pub use auth::JwtAlgorithm;
pub use auth::JwtConfig;
pub use auth::Principal;
pub use auth::StandardClaims;
pub use context::RequestContext;
pub use context::TransportType;
pub use handler::McpHandler;
pub use marker::MaybeSend;
pub use marker::MaybeSync;
pub use session::Cancellable;
pub use session::McpSession;
pub use session::SessionFuture;

Modules§

auth: Authentication traits and types for MCP servers.
context: Unified request context for MCP handlers.
error: Unified MCP error handling - no_std compatible.
error_codes: Protocol error codes (JSON-RPC standard + MCP extensions)
features: Protocol feature constants
handler: Unified MCP handler trait for cross-platform server implementations.
jsonrpc: JSON-RPC 2.0 types - no_std compatible.
marker: Platform-adaptive marker traits for cross-platform compatibility.
meta_keys: Keys TurboMCP writes into MCP _meta maps.
methods: Protocol method names (single source of truth)
response: Response traits for ergonomic tool handler returns.
rkyv_typeszero-copy: Zero-copy message types using rkyv serialization.
router: Shared MCP request router for all platforms.
security: Security utilities for error sanitization and input validation.
session: Bidirectional session and cancellation abstractions.
uri_template: Matching a URI against an RFC 6570 URI template.

Macros§

mcp_err: Convenience macro for creating errors with location

Structs§

Annotations: Annotations for content providing metadata.
AudioContent: Audio content (base64 encoded).
EmbeddedResource: Embedded resource content in a message.
Icon: Icon for tools, resources, prompts, or servers.
ImageContent: Image content (base64 encoded).
Message: A message in a prompt (PromptMessage per spec).
Prompt: Prompt definition.
PromptArgument: Argument definition for prompts.
PromptResult: Result from getting a prompt.
Resource: Resource definition.
ResourceAnnotations: Annotations for resources.
ResourceResult: Result from reading a resource.
ResourceTemplate: Resource template definition.
ServerInfo: Server information for MCP initialization.
TextContent: Text content with optional annotations.
Tool: Tool definition.
ToolAnnotations: Annotations for tools describing behavior hints.
ToolInputSchema: JSON Schema for tool input parameters.
ToolResult: Result from calling a tool.

Enums§

Content: Content block in MCP messages (ContentBlock per spec).
ResourceContents: Contents of a resource (text or binary).
Role: Role in a conversation or prompt message.

Constants§

DEFAULT_TIMEOUT_MS: Default timeout for operations in milliseconds
LOG_LEVELS: The eight logging severities MCP defines, in ascending order.
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 version strings.

Traits§

IntoPromptResult: Convert any type to a PromptResult.
IntoResourceResult: Convert any type to a ResourceResult.
IntoToolResult: Convert any type to a ToolResult.

Functions§

log_level_rank: Severity rank of a log level, or None if it is not one of LOG_LEVELS.