rmcp_actix_web/lib.rs
1//! # rmcp-actix-web
2//!
3#![warn(missing_docs)]
4//! actix-web transport implementations for RMCP (Rust Model Context Protocol).
5//!
6//! This crate provides HTTP-based transport layers for the [Model Context Protocol (MCP)][mcp],
7//! offering a complete alternative to the default Axum-based transports in the main [RMCP crate][rmcp].
8//! If you're already using actix-web in your application or prefer its API, this crate allows
9//! you to integrate MCP services seamlessly without introducing additional web frameworks.
10//!
11//! [mcp]: https://modelcontextprotocol.io/
12//! [rmcp]: https://crates.io/crates/rmcp
13//!
14//! ## Features
15//!
16//! - **[SSE (Server-Sent Events) Transport][SseService]** *(DEPRECATED)*: Real-time, unidirectional communication from server to client
17//! - **[Streamable HTTP Transport][StreamableHttpService]**: Bidirectional communication with session management
18//! - **Full MCP Compatibility**: Implements the complete MCP specification
19//! - **Drop-in Replacement**: Same service implementations work with either Axum or actix-web transports
20//! - **Production Ready**: Built on battle-tested actix-web framework
21//!
22//! ## Quick Start
23//!
24//! ### Streamable HTTP Server Example
25//!
26//! ```rust,no_run
27//! use rmcp_actix_web::transport::{StreamableHttpService, AuthorizationHeader};
28//! use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
29//! use rmcp::{ServerHandler, model::ServerInfo};
30//! use actix_web::{App, HttpServer};
31//! use std::{sync::Arc, time::Duration};
32//!
33//! # #[derive(Clone)]
34//! # struct MyMcpService;
35//! # impl ServerHandler for MyMcpService {
36//! # fn get_info(&self) -> ServerInfo { ServerInfo::default() }
37//! # }
38//! # impl MyMcpService {
39//! # fn new() -> Self { Self }
40//! # }
41//! #[actix_web::main]
42//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
43//! HttpServer::new(|| {
44//! let http_service = StreamableHttpService::builder()
45//! .service_factory(Arc::new(|| Ok(MyMcpService::new())))
46//! .session_manager(Arc::new(LocalSessionManager::default()))
47//! .stateful_mode(true)
48//! .sse_keep_alive(Duration::from_secs(30))
49//! .build();
50//!
51//! App::new()
52//! .service(http_service.scope())
53//! })
54//! .bind("127.0.0.1:8080")?
55//! .run()
56//! .await?;
57//!
58//! Ok(())
59//! }
60//! ```
61//!
62//! ## Transport Selection
63//!
64//! - **[Streamable HTTP][transport::streamable_http_server]**: Full bidirectional communication with session management
65//! - **[SSE Transport][transport::sse_server]** *(DEPRECATED)*: Legacy unidirectional transport, please migrate to StreamableHttp
66//!
67//! ## Examples
68//!
69//! See the `examples/` directory for complete working examples:
70//! - `counter_streamable_http.rs` - Streamable HTTP server example
71//! - `composition_streamable_http_example.rs` - StreamableHttp with custom mounting
72//! - `authorization_proxy_example.rs` - Authorization header forwarding example
73//!
74//! ## Framework-Level Composition
75//!
76//! Both transports support framework-level composition aligned with RMCP patterns,
77//! allowing you to mount MCP services at custom paths within existing actix-web applications.
78//!
79//! ### Service Composition
80//!
81//! ```rust,no_run
82//! use rmcp_actix_web::transport::{StreamableHttpService, AuthorizationHeader};
83//! use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
84//! use actix_web::{App, web};
85//! use std::{sync::Arc, time::Duration};
86//!
87//! # use rmcp::{ServerHandler, model::ServerInfo};
88//! # #[derive(Clone)]
89//! # struct MyService;
90//! # impl ServerHandler for MyService {
91//! # fn get_info(&self) -> ServerInfo { ServerInfo::default() }
92//! # }
93//! # impl MyService { fn new() -> Self { Self } }
94//! # use actix_web::HttpServer;
95//! # #[actix_web::main]
96//! # async fn main() -> std::io::Result<()> {
97//! HttpServer::new(|| {
98//! let http_service = StreamableHttpService::builder()
99//! .service_factory(Arc::new(|| Ok(MyService::new())))
100//! .session_manager(Arc::new(LocalSessionManager::default()))
101//! .stateful_mode(true)
102//! .sse_keep_alive(Duration::from_secs(30))
103//! .build();
104//!
105//! // Mount at custom path using scope()
106//! App::new()
107//! .service(web::scope("/api/v1/calculator").service(http_service.scope()))
108//! }).bind("127.0.0.1:8080")?.run().await
109//! # }
110//! ```
111//!
112//
113//! See the `examples/` directory for complete working examples of composition patterns.
114//!
115//! ## Performance Considerations
116//!
117//! - Streamable HTTP maintains persistent sessions which may use more memory
118//! - Uses efficient async I/O through actix-web's actor system
119//! - Framework-level composition adds minimal overhead
120//!
121//! ## Feature Flags
122//!
123//! This crate supports selective compilation of transport types:
124//!
125//! - `transport-streamable-http-server` (default): Enables StreamableHttp transport
126//! - `transport-sse-server` *(DEPRECATED)*: Enables legacy SSE transport
127//!
128//! To use only StreamableHttp transport, disable default features:
129//!
130//! ```toml
131//! [dependencies]
132//! rmcp-actix-web = { version = "0.6", default-features = false, features = ["transport-streamable-http-server"] }
133//! ```
134
135pub mod transport;