mcpkit_rocket/
lib.rs

1//! Rocket integration for the Rust MCP SDK.
2//!
3//! This crate provides integration between the MCP SDK and the Rocket web framework,
4//! making it easy to expose MCP servers over HTTP.
5//!
6//! # Features
7//!
8//! - HTTP POST endpoint for JSON-RPC messages
9//! - Server-Sent Events (SSE) streaming for notifications
10//! - Session management with automatic cleanup
11//! - Protocol version validation
12//! - CORS support via Rocket fairings
13//!
14//! # HTTP Protocol Requirements
15//!
16//! Clients must include the `Mcp-Protocol-Version` header in all requests:
17//!
18//! ```text
19//! POST /mcp HTTP/1.1
20//! Content-Type: application/json
21//! Mcp-Protocol-Version: 2025-11-25
22//!
23//! {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
24//! ```
25//!
26//! Supported protocol versions: `2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25`
27//!
28//! # Quick Start
29//!
30//! ```ignore
31//! use mcpkit::prelude::*;
32//! use mcpkit_rocket::McpRouter;
33//!
34//! // Your MCP server handler (use #[mcp_server] macro)
35//! #[mcp_server(name = "my-server", version = "1.0.0")]
36//! impl MyServer {
37//!     #[tool(description = "Say hello")]
38//!     async fn hello(&self, name: String) -> ToolOutput {
39//!         ToolOutput::text(format!("Hello, {name}!"))
40//!     }
41//! }
42//!
43//! #[rocket::main]
44//! async fn main() -> Result<(), rocket::Error> {
45//!     McpRouter::new(MyServer::new())
46//!         .launch()
47//!         .await?;
48//!     Ok(())
49//! }
50//! ```
51//!
52//! # Advanced Usage
53//!
54//! For more control, use `into_rocket()` to integrate with an existing app:
55//!
56//! ```ignore
57//! use mcpkit_rocket::McpRouter;
58//! use rocket::{Build, Rocket};
59//!
60//! fn build_app() -> Rocket<Build> {
61//!     let mcp = McpRouter::new(MyServer::new())
62//!         .with_cors();
63//!
64//!     rocket::build()
65//!         .attach(mcp.into_fairing())
66//!         .mount("/health", routes![health_check])
67//! }
68//!
69//! #[rocket::get("/")]
70//! fn health_check() -> &'static str {
71//!     "OK"
72//! }
73//! ```
74//!
75//! # Client Example (curl)
76//!
77//! ```bash
78//! # Initialize the connection
79//! curl -X POST http://localhost:8000/mcp \
80//!   -H "Content-Type: application/json" \
81//!   -H "Mcp-Protocol-Version: 2025-11-25" \
82//!   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}'
83//!
84//! # List available tools
85//! curl -X POST http://localhost:8000/mcp \
86//!   -H "Content-Type: application/json" \
87//!   -H "Mcp-Protocol-Version: 2025-11-25" \
88//!   -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
89//! ```
90
91#![deny(missing_docs)]
92
93mod error;
94/// Handler module for MCP request processing.
95pub mod handler;
96mod router;
97mod session;
98mod state;
99
100pub use error::RocketError;
101pub use handler::{
102    LastEventIdHeader, McpResponse, ProtocolVersionHeader, SessionIdHeader, handle_mcp_post,
103    handle_sse,
104};
105pub use router::{Cors, McpRouter};
106pub use session::{SessionManager, SessionStore};
107pub use state::McpState;
108
109/// Prelude module for convenient imports.
110///
111/// # Example
112///
113/// ```ignore
114/// use mcpkit_rocket::prelude::*;
115/// ```
116pub mod prelude {
117    pub use crate::error::RocketError;
118    pub use crate::handler::{handle_mcp_post, handle_sse};
119    pub use crate::router::McpRouter;
120    pub use crate::session::{SessionManager, SessionStore};
121    pub use crate::state::McpState;
122}
123
124/// Protocol versions supported by this extension.
125pub const SUPPORTED_VERSIONS: &[&str] = &["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"];
126
127/// Check if a protocol version is supported.
128#[must_use]
129pub fn is_supported_version(version: Option<&str>) -> bool {
130    version.is_some_and(|v| SUPPORTED_VERSIONS.contains(&v))
131}
mcpkit_rocket/lib.rs

mcpkit_rocket/
lib.rs
