turul_http_mcp_server/
lib.rs

1//! # HTTP MCP Server
2//!
3//! **Production HTTP transport layer for Model Context Protocol (MCP) servers.**
4//!
5//! Provides both modern Streamable HTTP and legacy HTTP+SSE transports with automatic
6//! protocol detection, CORS support, and session management for maximum compatibility.
7//!
8//! [![Crates.io](https://img.shields.io/crates/v/turul-http-mcp-server.svg)](https://crates.io/crates/turul-http-mcp-server)
9//! [![Documentation](https://docs.rs/turul-http-mcp-server/badge.svg)](https://docs.rs/turul-http-mcp-server)
10//!
11//! ## Installation
12//!
13//! ```toml
14//! [dependencies]
15//! turul-http-mcp-server = "0.3"
16//! turul-mcp-server = "0.3"
17//! ```
18//!
19//! ## Supported Transports
20//! - **Streamable HTTP**: Recommended for production deployments
21//! - **HTTP+SSE**: Legacy transport for backwards compatibility
22//!
23//! ## Features
24//! - Automatic protocol version detection and routing
25//! - CORS support for browser-based clients
26//! - Session management with cryptographically secure IDs
27//! - Graceful error handling and JSON-RPC 2.0 compliance
28//!
29//! ## Quick Start
30//!
31//! ```rust,no_run
32//! use turul_http_mcp_server::HttpMcpServerBuilder;
33//! use std::net::SocketAddr;
34//!
35//! #[tokio::main]
36//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
37//!     let addr: SocketAddr = "127.0.0.1:8080".parse()?;
38//!     let server = HttpMcpServerBuilder::new()
39//!         .bind_address(addr)
40//!         .cors(true)
41//!         .build();
42//!
43//!     println!("Server running on http://127.0.0.1:8080/mcp");
44//!     server.run().await?;
45//!     Ok(())
46//! }
47//! ```
48
49pub mod cors;
50pub mod handler;
51pub mod json_rpc_responses;
52pub mod mcp_session;
53pub mod middleware;
54pub mod notification_bridge;
55pub mod prelude;
56pub mod protocol;
57pub mod routes;
58pub mod server;
59pub mod session_handler;
60pub mod sse;
61pub mod stream_manager;
62pub mod streamable_http;
63
64#[cfg(test)]
65mod tests;
66
67// Re-export main types
68pub use cors::CorsLayer;
69// McpHttpHandler removed in 0.2.0 - use SessionMcpHandler instead
70pub use notification_bridge::{
71    BroadcastError, NotificationBroadcaster, SharedNotificationBroadcaster,
72    StreamManagerNotificationBroadcaster,
73};
74pub use protocol::{
75    McpProtocolVersion, extract_last_event_id, extract_protocol_version, extract_session_id,
76};
77pub use routes::{RouteBody, RouteHandler, RouteRegistry, RouteValidationError};
78/// HTTP MCP server implementation with builder pattern and configuration
79pub use server::{HttpMcpServer, HttpMcpServerBuilder, ServerConfig, ServerStats};
80/// Session-aware request handler with SSE streaming capabilities
81pub use session_handler::{SessionMcpHandler, SessionSseStream};
82/// SSE stream management with connection tracking and event delivery
83pub use stream_manager::{StreamConfig, StreamError, StreamManager, StreamStats};
84pub use streamable_http::{StreamableHttpContext, StreamableHttpHandler};
85
86/// Awaitable notifier for tool change events (restart/redeploy fingerprint mismatch).
87/// Implemented by the server layer (backed by SessionManager → dispatcher).
88/// Used by HTTP handlers to persist `notifications/tools/list_changed` through
89/// the session architecture, not directly via StreamManager.
90#[async_trait::async_trait]
91pub trait ToolChangeNotifier: Send + Sync {
92    async fn notify_tools_changed(&self, session_id: &str) -> std::result::Result<(), String>;
93}
94
95// Re-export foundational types
96/// JSON-RPC 2.0 dispatcher and handler trait for protocol operations
97pub use turul_mcp_json_rpc_server::{JsonRpcDispatcher, JsonRpcHandler};
98/// Core MCP protocol types and error handling
99pub use turul_mcp_protocol::*;
100
101/// Result type for HTTP MCP operations
102pub type Result<T> = std::result::Result<T, HttpMcpError>;
103
104/// HTTP MCP specific errors
105#[derive(Debug, thiserror::Error)]
106pub enum HttpMcpError {
107    #[error("HTTP error: {0}")]
108    Http(#[from] hyper::Error),
109
110    #[error("JSON-RPC error: {0}")]
111    JsonRpc(#[from] turul_mcp_json_rpc_server::JsonRpcError),
112
113    #[error("MCP protocol error: {0}")]
114    Mcp(#[from] turul_mcp_protocol::McpError),
115
116    #[error("Serialization error: {0}")]
117    Serialization(#[from] serde_json::Error),
118
119    #[error("IO error: {0}")]
120    Io(#[from] std::io::Error),
121
122    #[error("Invalid request: {0}")]
123    InvalidRequest(String),
124}
turul_http_mcp_server/lib.rs

turul_http_mcp_server/
lib.rs
