turul-http-mcp-server 0.3.33

HTTP transport layer for Model Context Protocol (MCP) servers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! # HTTP MCP Server
//!
//! **Production HTTP transport layer for Model Context Protocol (MCP) servers.**
//!
//! Provides both modern Streamable HTTP and legacy HTTP+SSE transports with automatic
//! protocol detection, CORS support, and session management for maximum compatibility.
//!
//! [![Crates.io](https://img.shields.io/crates/v/turul-http-mcp-server.svg)](https://crates.io/crates/turul-http-mcp-server)
//! [![Documentation](https://docs.rs/turul-http-mcp-server/badge.svg)](https://docs.rs/turul-http-mcp-server)
//!
//! ## Installation
//!
//! ```toml
//! [dependencies]
//! turul-http-mcp-server = "0.3"
//! turul-mcp-server = "0.3"
//! ```
//!
//! ## Supported Transports
//! - **Streamable HTTP**: Recommended for production deployments
//! - **HTTP+SSE**: Legacy transport for backwards compatibility
//!
//! ## Features
//! - Automatic protocol version detection and routing
//! - CORS support for browser-based clients
//! - Session management with cryptographically secure IDs
//! - Graceful error handling and JSON-RPC 2.0 compliance
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use turul_http_mcp_server::HttpMcpServerBuilder;
//! use std::net::SocketAddr;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let addr: SocketAddr = "127.0.0.1:8080".parse()?;
//!     let server = HttpMcpServerBuilder::new()
//!         .bind_address(addr)
//!         .cors(true)
//!         .build();
//!
//!     println!("Server running on http://127.0.0.1:8080/mcp");
//!     server.run().await?;
//!     Ok(())
//! }
//! ```

pub mod cors;
pub mod handler;
pub mod json_rpc_responses;
pub mod mcp_session;
pub mod middleware;
pub mod notification_bridge;
pub mod prelude;
pub mod protocol;
pub mod routes;
pub mod server;
pub mod session_handler;
pub mod sse;
pub mod stream_manager;
pub mod streamable_http;

#[cfg(test)]
mod tests;

// Re-export main types
pub use cors::CorsLayer;
// McpHttpHandler removed in 0.2.0 - use SessionMcpHandler instead
pub use notification_bridge::{
    BroadcastError, NotificationBroadcaster, SharedNotificationBroadcaster,
    StreamManagerNotificationBroadcaster,
};
pub use protocol::{
    McpProtocolVersion, extract_last_event_id, extract_protocol_version, extract_session_id,
};
pub use routes::{RouteBody, RouteHandler, RouteRegistry, RouteValidationError};
/// HTTP MCP server implementation with builder pattern and configuration
pub use server::{HttpMcpServer, HttpMcpServerBuilder, ServerConfig, ServerStats};
/// Session-aware request handler with SSE streaming capabilities
pub use session_handler::{SessionMcpHandler, SessionSseStream};
/// SSE stream management with connection tracking and event delivery
pub use stream_manager::{StreamConfig, StreamError, StreamManager, StreamStats};
pub use streamable_http::{StreamableHttpContext, StreamableHttpHandler};

/// Awaitable notifier for tool change events (restart/redeploy fingerprint mismatch).
/// Implemented by the server layer (backed by SessionManager → dispatcher).
/// Used by HTTP handlers to persist `notifications/tools/list_changed` through
/// the session architecture, not directly via StreamManager.
#[async_trait::async_trait]
pub trait ToolChangeNotifier: Send + Sync {
    async fn notify_tools_changed(&self, session_id: &str) -> std::result::Result<(), String>;
}

// Re-export foundational types
/// JSON-RPC 2.0 dispatcher and handler trait for protocol operations
pub use turul_mcp_json_rpc_server::{JsonRpcDispatcher, JsonRpcHandler};
/// Core MCP protocol types and error handling
pub use turul_mcp_protocol::*;

/// Result type for HTTP MCP operations
pub type Result<T> = std::result::Result<T, HttpMcpError>;

/// HTTP MCP specific errors
#[derive(Debug, thiserror::Error)]
pub enum HttpMcpError {
    #[error("HTTP error: {0}")]
    Http(#[from] hyper::Error),

    #[error("JSON-RPC error: {0}")]
    JsonRpc(#[from] turul_mcp_json_rpc_server::JsonRpcError),

    #[error("MCP protocol error: {0}")]
    Mcp(#[from] turul_mcp_protocol::McpError),

    #[error("Serialization error: {0}")]
    Serialization(#[from] serde_json::Error),

    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("Invalid request: {0}")]
    InvalidRequest(String),
}