Crate turul_mcp_server

Expand description

§MCP Server Framework

A production-ready Rust framework for building Model Context Protocol (MCP) servers. Provides zero-configuration setup, comprehensive MCP 2025-06-18 specification support, and multiple deployment targets including HTTP, AWS Lambda, and local development.

§Features

Zero Configuration: Framework auto-determines method strings from types
Type-Safe Error Handling: Clean domain/protocol separation
4 Tool Creation Levels: Function macros → derive macros → builders → manual
Multiple Transports: HTTP, Server-Sent Events (SSE), AWS Lambda
Pluggable Storage: InMemory, SQLite, PostgreSQL, DynamoDB
Real-time Streaming: SSE notifications for progress and logging
Production Ready: Comprehensive testing, monitoring, and deployment support

§Installation

Add to your Cargo.toml:

[dependencies]
turul-mcp-server = "0.2"
turul-mcp-derive = "0.2"  # For macros
tokio = { version = "1.0", features = ["full"] }

§Quick Start

// Create a basic MCP server with detailed configuration
let server = McpServer::builder()
    .name("calculator-server")
    .version("1.0.0")
    .title("Advanced Calculator Server")
    .instructions("A production-grade calculator server supporting basic arithmetic operations including addition, subtraction, multiplication, and division. Use the available tools to perform calculations. The server maintains session state for calculation history, supports real-time notifications for long-running computations, and provides detailed error reporting for invalid operations.")
    .build()?;

server.run().await

§Architecture

The framework uses clean domain/protocol separation:

Domain Layer: Tools return McpResult<T> with domain errors
Protocol Layer: Framework converts to JSON-RPC 2.0 automatically
Transport Layer: HTTP/SSE with session-aware error handling
Storage Layer: Pluggable backends (InMemory, SQLite, PostgreSQL, DynamoDB)

§Examples

Complete working examples available at: github.com/aussierobots/turul-mcp-framework/tree/main/examples

Minimal Server - Basic tool setup
Calculator - Math operations with error handling
HTTP Server - Production HTTP deployment
AWS Lambda - Serverless deployment
Real-time Streaming - SSE notifications
Database Integration - SQLite/PostgreSQL/DynamoDB

§Deployment Options

§Local Development

cargo run --example minimal-server
# Server runs on http://localhost:8080/mcp

§AWS Lambda

cargo lambda build --release
cargo lambda deploy --iam-role arn:aws:iam::...

§Docker

FROM rust:1.70 as builder
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /target/release/my-mcp-server /usr/local/bin/
EXPOSE 8080
CMD ["my-mcp-server"]

§Configuration

The framework supports extensive configuration through the builder pattern:

let server = McpServer::builder()
    .name("production-server")
    .version("1.0.0")
    .title("Production MCP Server")
    .instructions("This production server provides tools for database operations, file management, and API integrations. Use the 'database/query' tool for SQL operations, 'files/read' for file access, and 'api/call' for external service integration. Session management is enabled with SQLite persistence for reliability.")
    .with_session_storage(std::sync::Arc::new(SqliteSessionStorage::new().await?))
    .build()?;

Re-exports§

pub use builder::McpServerBuilder;
pub use completion::McpCompletion;
pub use dispatch::DispatchContext;
pub use dispatch::DispatchMiddleware;
pub use dispatch::McpDispatcher;
pub use elicitation::McpElicitation;
pub use logging::McpLogger;
pub use notifications::McpNotification;
pub use prompt::McpPrompt;
pub use resource::McpResource;
pub use roots::McpRoot;
pub use sampling::McpSampling;
pub use security::AccessLevel;
pub use security::InputValidator;
pub use security::RateLimitConfig;
pub use security::ResourceAccessControl;
pub use security::SecurityMiddleware;
pub use server::ListToolsHandler;
pub use server::McpServer;
pub use server::SessionAwareInitializeHandler;
pub use server::SessionAwareMcpHandlerBridge;
pub use server::SessionAwareToolHandler;
pub use session::SessionContext;
pub use session::SessionEvent;
pub use session::SessionManager;
pub use tool::McpTool;
pub use turul_mcp_session_storage as session_storage;
pub use turul_http_mcp_server;
pub use handlers::*;

Modules§

builder: MCP Server Builder
completion: MCP Completion Trait
content: Core MCP protocol types, errors, and specification compliance Content types for MCP 2025-06-18 specification
dispatch
elicitation: MCP Elicitation Trait
handlers: MCP Handler System
http: HTTP transport support for MCP servers
initialize: Core MCP protocol types, errors, and specification compliance MCP Initialize Protocol Types
json_rpc: Core MCP protocol types, errors, and specification compliance JSON-RPC 2.0 Implementation for MCP 2025-06-18
logging: MCP Logging Trait
meta: Core MCP protocol types, errors, and specification compliance _meta Field Support for MCP 2025-06-18
middleware: Middleware system for MCP servers
notifications: MCP Notifications Trait
param_extraction: Core MCP protocol types, errors, and specification compliance Parameter extraction utilities for MCP protocol
ping: Core MCP protocol types, errors, and specification compliance MCP Ping Protocol Types
prelude: Prelude module for common MCP server imports
prompt: MCP Prompt Trait
prompts: Core MCP protocol types, errors, and specification compliance MCP Prompts Protocol Types
resource: MCP Resource Trait
resources: Core MCP protocol types, errors, and specification compliance MCP Resources Protocol Types
roots: MCP Roots Trait
sampling: MCP Sampling Trait
schema: Core MCP protocol types, errors, and specification compliance JSON Schema Support for MCP
security: Security Controls for MCP Server
server: MCP Server Implementation and Session-Aware Handlers
session: Session Management for MCP Servers
tool: MCP Tool Trait
tools: Core MCP protocol types, errors, and specification compliance MCP Tools Protocol Types
traits: Core MCP protocol types, errors, and specification compliance Traits for JSON-RPC types as per MCP specification (2025-06-18)
uri_template: URI Template System for Dynamic Resources
version: Core MCP protocol types, errors, and specification compliance MCP Protocol Version Support

Macros§

impl_serde_extractor: Core MCP protocol types, errors, and specification compliance Macro to implement SerdeParamExtractor for any Params type that implements Deserialize

Structs§

Annotations: Core MCP protocol types, errors, and specification compliance Generic annotations structure (matches TypeScript Annotations) Used across all MCP types that support client annotations
BlobResourceContents: Core MCP protocol types, errors, and specification compliance Binary resource contents (matches TypeScript BlobResourceContents exactly)
CallToolRequest: Core MCP protocol types, errors, and specification compliance Complete tools/call request (matches TypeScript CallToolRequest interface)
CallToolResult: Core MCP protocol types, errors, and specification compliance Result for tools/call (per MCP spec)
CancelledNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/cancelled”
ClientCapabilities: Core MCP protocol types, errors, and specification compliance Capabilities that a client may support
DynamicTool: Dynamic tool creation with runtime configuration and type-safe builders Dynamic tool created by ToolBuilder
ElicitCreateParams: Core MCP protocol types, errors, and specification compliance Parameters for elicitation/create request (per MCP spec)
ElicitCreateRequest: Core MCP protocol types, errors, and specification compliance Complete elicitation/create request (matches TypeScript ElicitRequest interface)
ElicitResult: Core MCP protocol types, errors, and specification compliance The client’s response to an elicitation request (per MCP spec)
ElicitationBuilder: Core MCP protocol types, errors, and specification compliance Builder for creating common elicitation patterns
ElicitationSchema: Core MCP protocol types, errors, and specification compliance Restricted schema for elicitation (only primitive types, no nesting) - per MCP spec
EmptyParams: Core MCP protocol types, errors, and specification compliance
EmptyResult: Core MCP protocol types, errors, and specification compliance Empty result for successful operations (per MCP spec)
GetPromptRequest: Core MCP protocol types, errors, and specification compliance Complete prompts/get request (matches TypeScript GetPromptRequest interface)
GetPromptResult: Core MCP protocol types, errors, and specification compliance Result for prompts/get (per MCP spec)
Implementation: Core MCP protocol types, errors, and specification compliance Describes the name and version of an MCP implementation
InitializeRequest: Core MCP protocol types, errors, and specification compliance Parameters for initialize request
InitializeResult: Core MCP protocol types, errors, and specification compliance Result payload for initialize (per MCP spec)
InitializedNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/initialized”
JsonRpcDispatcher: JSON-RPC 2.0 request dispatcher and handler trait for protocol operations JSON-RPC method dispatcher with specific error type
JsonRpcError: Core MCP protocol types, errors, and specification compliance JSON-RPC 2.0 error object
JsonRpcNotification: Core MCP protocol types, errors, and specification compliance A JSON-RPC 2.0 notification (no response expected)
JsonRpcRequest: Core MCP protocol types, errors, and specification compliance A standard JSON-RPC 2.0 request
JsonRpcResponse: Core MCP protocol types, errors, and specification compliance A standard JSON-RPC 2.0 response
ListPromptsRequest: Core MCP protocol types, errors, and specification compliance Complete prompts/list request (matches TypeScript ListPromptsRequest interface)
ListPromptsResult: Core MCP protocol types, errors, and specification compliance Result for prompts/list (per MCP spec)
ListResourcesRequest: Core MCP protocol types, errors, and specification compliance Complete resources/list request (matches TypeScript ListResourcesRequest interface)
ListResourcesResult: Core MCP protocol types, errors, and specification compliance Result for resources/list (per MCP spec)
ListToolsRequest: Core MCP protocol types, errors, and specification compliance Complete tools/list request (matches TypeScript ListToolsRequest interface)
ListToolsResult: Core MCP protocol types, errors, and specification compliance Result for tools/list (per MCP spec) - extends PaginatedResult
LoggingMessageNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/message”
LoggingMessageNotificationParams: Core MCP protocol types, errors, and specification compliance
Meta: Core MCP protocol types, errors, and specification compliance Structured _meta field for MCP 2025-06-18
MetaCursor: Core MCP protocol types, errors, and specification compliance Cursor for pagination support
Notification: Core MCP protocol types, errors, and specification compliance Base notification structure following MCP TypeScript specification
NotificationParams: Core MCP protocol types, errors, and specification compliance Base notification parameters that can include _meta
PaginatedResponse: Core MCP protocol types, errors, and specification compliance Helper for pagination responses
PingRequest: Core MCP protocol types, errors, and specification compliance Request for ping (per MCP spec)
ProgressNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/progress”
ProgressNotificationParams: Core MCP protocol types, errors, and specification compliance
ProgressResponse: Core MCP protocol types, errors, and specification compliance Helper for progress responses
ProgressToken: Core MCP protocol types, errors, and specification compliance Progress token for tracking long-running operations
Prompt: Core MCP protocol types, errors, and specification compliance A prompt descriptor (matches TypeScript Prompt interface exactly)
PromptArgument: Core MCP protocol types, errors, and specification compliance Argument definition for prompts (extends BaseMetadata per MCP spec)
PromptListChangedNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/prompts/listChanged” (per MCP spec)
PromptMessage: Core MCP protocol types, errors, and specification compliance Message content for prompts (matches MCP PromptMessage interface exactly)
ReadResourceRequest: Core MCP protocol types, errors, and specification compliance Complete resources/read request (matches TypeScript ReadResourceRequest interface)
ReadResourceResult: Core MCP protocol types, errors, and specification compliance Result for resources/read (per MCP spec)
RequestParams: Core MCP protocol types, errors, and specification compliance JSON-RPC params object with optional _meta and method-specific arguments
Resource: Core MCP protocol types, errors, and specification compliance A resource descriptor (matches TypeScript Resource interface) Resource extends BaseMetadata, so it includes name and title fields
ResourceListChangedNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/resources/listChanged” (per MCP spec)
ResourceReference: Core MCP protocol types, errors, and specification compliance Resource reference for resource links (matches TypeScript Resource interface)
ResourceSubscription: Core MCP protocol types, errors, and specification compliance Resource subscription parameters
ResourceUpdatedNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/resources/updated”
ResourceUpdatedNotificationParams: Core MCP protocol types, errors, and specification compliance
ResultWithMeta: Core MCP protocol types, errors, and specification compliance A generic result wrapper that combines data with optional _meta information
RootsListChangedNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/roots/listChanged” (per MCP spec)
ServerCapabilities: Core MCP protocol types, errors, and specification compliance Capabilities that a server may support
SubscribeRequest: Core MCP protocol types, errors, and specification compliance Complete resources/subscribe request (per MCP spec)
TextResourceContents: Core MCP protocol types, errors, and specification compliance Text resource contents (matches TypeScript TextResourceContents exactly)
Tool: Core MCP protocol types, errors, and specification compliance Tool definition
ToolBuilder: Dynamic tool creation with runtime configuration and type-safe builders Builder for creating tools at runtime
ToolListChangedNotification: Core MCP protocol types, errors, and specification compliance Method: “notifications/tools/listChanged” (per MCP spec)
ToolSchema: Core MCP protocol types, errors, and specification compliance JSON Schema definition for tool input/output (matches TypeScript spec exactly) Must be an object with type: “object”, properties, and required fields
UnsubscribeRequest: Core MCP protocol types, errors, and specification compliance Complete resources/unsubscribe request (per MCP spec)

Enums§

ContentBlock: Core MCP protocol types, errors, and specification compliance Content block union type matching MCP 2025-06-18 specification exactly
ElicitAction: Core MCP protocol types, errors, and specification compliance User action in response to elicitation
JsonRpcMessage: Core MCP protocol types, errors, and specification compliance Unified JSON-RPC message type
JsonSchema: Core MCP protocol types, errors, and specification compliance A JSON Schema definition
LegacyRequestParams: Core MCP protocol types, errors, and specification compliance Parameters for a JSON-RPC request
McpError: Domain error type for MCP operations with protocol conversion support MCP-specific errors
McpVersion: Core MCP protocol types, errors, and specification compliance Supported MCP protocol versions
PrimitiveSchemaDefinition: Core MCP protocol types, errors, and specification compliance Restricted schema definitions that only allow primitive types without nested objects or arrays (per MCP spec).
RequestId: Core MCP protocol types, errors, and specification compliance A uniquely identifying ID for a JSON-RPC request. Can be a string or a number, but never null.
ResourceContent: Core MCP protocol types, errors, and specification compliance Union type for resource contents (matches TypeScript union)
ResourceContents: Core MCP protocol types, errors, and specification compliance Resource contents union type (matches TypeScript TextResourceContents | BlobResourceContents)
ResponseResult: Core MCP protocol types, errors, and specification compliance Result data for a JSON-RPC response
StringFormat: Core MCP protocol types, errors, and specification compliance String format constraints

Constants§

CURRENT_VERSION: Core MCP protocol types, errors, and specification compliance The current MCP protocol version implemented by this crate
MCP_VERSION: Core MCP protocol types, errors, and specification compliance The MCP protocol version implemented by this crate

Traits§

HasData: Core MCP protocol types, errors, and specification compliance
HasDataParam: Core MCP protocol types, errors, and specification compliance
HasMeta: Core MCP protocol types, errors, and specification compliance
HasMetaParam: Core MCP protocol types, errors, and specification compliance
HasProgressTokenParam: Core MCP protocol types, errors, and specification compliance
JsonRpcHandler: JSON-RPC 2.0 request dispatcher and handler trait for protocol operations Trait for handling JSON-RPC method calls
JsonRpcNotificationTrait: Core MCP protocol types, errors, and specification compliance
JsonRpcRequestTrait: Core MCP protocol types, errors, and specification compliance
JsonRpcResponseTrait: Core MCP protocol types, errors, and specification compliance
Params: Core MCP protocol types, errors, and specification compliance
RpcResult: Core MCP protocol types, errors, and specification compliance
SessionView: SessionView trait for middleware - re-exported from turul-mcp-session-storage Minimal session interface for middleware access
WithMeta: Core MCP protocol types, errors, and specification compliance Trait for types that can include _meta fields

Type Aliases§

DynamicToolFn: Dynamic tool creation with runtime configuration and type-safe builders Type alias for dynamic tool execution function
McpResult: Result type for MCP server operations with domain-specific error handling
ProtocolMcpResult: Domain error type for MCP operations with protocol conversion support Common result type for MCP operations
Result: Convenience alias for McpResult
ToolResult: Core MCP protocol types, errors, and specification compliance Tool result type - an alias for ContentBlock to maintain backward compatibility while ensuring MCP 2025-06-18 specification compliance

Crate turul_mcp_server

Crate turul_mcp_server Copy item path

§MCP Server Framework

§Features

§Installation

§Quick Start

§Architecture

§Examples

§Deployment Options

§Local Development

§AWS Lambda

§Docker

§Configuration

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Crate turul_mcp_server