turbomcp_http/lib.rs
1//! # TurboMCP HTTP Transport
2//!
3//! MCP 2025-11-25 compliant HTTP/SSE client transport implementation.
4//!
5//! This crate provides the HTTP client transport for the Model Context Protocol (MCP),
6//! implementing the Streamable HTTP transport specification with full SSE support.
7//!
8//! ## Features
9//!
10//! - **MCP 2025-11-25 Specification Compliance**: Full implementation of the streamable HTTP spec
11//! - **Single Endpoint Design**: All communication through one MCP endpoint
12//! - **SSE Support**: Server-Sent Events for server-to-client streaming
13//! - **Endpoint Discovery**: Automatic endpoint URI discovery via SSE events
14//! - **Session Management**: Mcp-Session-Id header support for session tracking
15//! - **Auto-Reconnect**: Configurable retry policies with exponential backoff
16//! - **Last-Event-ID Resumability**: Resume SSE streams from last received event
17//! - **TLS 1.3**: Minimum TLS version enforcement for security
18//! - **Size Limits**: Configurable request/response size validation
19//!
20//! ## Usage
21//!
22//! ```rust,no_run
23//! use turbomcp_http::{StreamableHttpClientTransport, StreamableHttpClientConfig};
24//! use turbomcp_transport_traits::Transport;
25//! use std::time::Duration;
26//!
27//! #[tokio::main]
28//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
29//! let config = StreamableHttpClientConfig {
30//! base_url: "http://localhost:8080".to_string(),
31//! endpoint_path: "/mcp".to_string(),
32//! timeout: Duration::from_secs(30),
33//! ..Default::default()
34//! };
35//!
36//! let transport = StreamableHttpClientTransport::new(config)?;
37//! transport.connect().await?;
38//!
39//! // Transport is ready for MCP communication
40//! println!("HTTP transport connected");
41//! Ok(())
42//! }
43//! ```
44//!
45//! ## MCP Protocol Flow
46//!
47//! 1. Client connects and optionally opens SSE stream (GET with Accept: text/event-stream)
48//! 2. Server may send "endpoint" event with message endpoint URI
49//! 3. Client sends requests via POST to message endpoint
50//! 4. Server responds with JSON or SSE stream (Accept header negotiation)
51//! 5. Client terminates session with DELETE request
52//!
53//! ## Configuration Options
54//!
55//! ```rust
56//! use turbomcp_http::{StreamableHttpClientConfig, RetryPolicy};
57//! use turbomcp_transport_traits::{LimitsConfig, TlsConfig};
58//! use std::time::Duration;
59//!
60//! let config = StreamableHttpClientConfig {
61//! base_url: "https://api.example.com".to_string(),
62//! endpoint_path: "/mcp".to_string(),
63//! timeout: Duration::from_secs(30),
64//! retry_policy: RetryPolicy::Exponential {
65//! base: Duration::from_secs(1),
66//! max_delay: Duration::from_secs(60),
67//! max_attempts: Some(10),
68//! },
69//! auth_token: Some("your-token".to_string()),
70//! limits: LimitsConfig::default(),
71//! tls: TlsConfig::modern(),
72//! ..Default::default()
73//! };
74//! ```
75//!
76//! ## Security
77//!
78//! - TLS 1.3 is required by default (v3.0 security requirement)
79//! - Certificate validation is enabled by default
80//! - Disabling certificate validation requires explicit environment variable opt-in
81//! - Request/response size limits prevent resource exhaustion attacks
82
83#![warn(
84 missing_docs,
85 missing_debug_implementations,
86 rust_2018_idioms,
87 unreachable_pub,
88 clippy::all
89)]
90#![deny(unsafe_code)]
91#![cfg_attr(docsrs, feature(doc_cfg))]
92
93mod transport;
94
95// Re-export the transport implementation
96pub use transport::{RetryPolicy, StreamableHttpClientConfig, StreamableHttpClientTransport};
97
98// Re-export common types from traits crate for convenience
99pub use turbomcp_transport_traits::{
100 LimitsConfig, TlsConfig, TlsVersion, Transport, TransportCapabilities, TransportError,
101 TransportMessage, TransportMetrics, TransportResult, TransportState, TransportType,
102};