feat: unified error type (modelcontextprotocol#308)

* feat: unified error type

* fix: use type id to compare transport type

Author: 4t145

crates/rmcp-macros/README.md

@@ -134,7 +134,7 @@ impl ServerHandler for MyToolHandler {
         &self,
         request: CallToolRequestParam,
         context: RequestContext<RoleServer>,
-    ) -> Result<CallToolResult, rmcp::Error> {
+    ) -> Result<CallToolResult, rmcp::ErrorData> {
         let tcc = ToolCallContext::new(self, request, context);
         self.tool_router.call(tcc).await
     }
@@ -143,7 +143,7 @@ impl ServerHandler for MyToolHandler {
         &self,
         _request: Option<PaginatedRequestParam>,
         _context: RequestContext<RoleServer>,
-    ) -> Result<ListToolsResult, rmcp::Error> {
+    ) -> Result<ListToolsResult, rmcp::ErrorData> {
         let items = self.tool_router.list_all();
         Ok(ListToolsResult::with_all_items(items))
     }

crates/rmcp-macros/src/lib.rs

@@ -139,7 +139,7 @@ pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
 ///         &self,
 ///         request: CallToolRequestParam,
 ///         context: RequestContext<RoleServer>,
-///     ) -> Result<CallToolResult, rmcp::Error> {
+///     ) -> Result<CallToolResult, rmcp::ErrorData> {
 ///         let tcc = ToolCallContext::new(self, request, context);
 ///         self.tool_router.call(tcc).await
 ///     }
@@ -148,7 +148,7 @@ pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
 ///         &self,
 ///         _request: Option<PaginatedRequestParam>,
 ///         _context: RequestContext<RoleServer>,
-///     ) -> Result<ListToolsResult, rmcp::Error> {
+///     ) -> Result<ListToolsResult, rmcp::ErrorData> {
 ///         let items = self.tool_router.list_all();
 ///         Ok(ListToolsResult::with_all_items(items))
 ///     }

crates/rmcp-macros/src/tool_handler.rs

@@ -29,7 +29,7 @@ pub fn tool_handler(attr: TokenStream, input: TokenStream) -> syn::Result<TokenS
             &self,
             request: rmcp::model::CallToolRequestParam,
             context: rmcp::service::RequestContext<rmcp::RoleServer>,
-        ) -> Result<rmcp::model::CallToolResult, rmcp::Error> {
+        ) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
             let tcc = rmcp::handler::server::tool::ToolCallContext::new(self, request, context);
             #router.call(tcc).await
         }
@@ -39,7 +39,7 @@ pub fn tool_handler(attr: TokenStream, input: TokenStream) -> syn::Result<TokenS
             &self,
             _request: Option<rmcp::model::PaginatedRequestParam>,
             _context: rmcp::service::RequestContext<rmcp::RoleServer>,
-        ) -> Result<rmcp::model::ListToolsResult, rmcp::Error> {
+        ) -> Result<rmcp::model::ListToolsResult, rmcp::ErrorData> {
             Ok(rmcp::model::ListToolsResult::with_all_items(#router.list_all()))
         }
     };

crates/rmcp/README.md

@@ -15,7 +15,7 @@ wait for the first release.
 Creating a server with tools is simple using the `#[tool]` macro:
 
 ```rust, ignore
-use rmcp::{Error as McpError, ServiceExt, model::*, tool, tool_handler, tool_router, transport::stdio, handler::server::router::tool::ToolRouter};
+use rmcp::{ErrorData as McpError, ServiceExt, model::*, tool, tool_router, transport::stdio, handler::server::tool::ToolCallContext, handler::server::router::tool::ToolRouter};
 use std::sync::Arc;
 use tokio::sync::Mutex;
 

crates/rmcp/src/error.rs

@@ -1,9 +1,11 @@
-use std::fmt::Display;
-
-use crate::model::ErrorData;
+use std::{borrow::Cow, fmt::Display};
 
+use crate::ServiceError;
+pub use crate::model::ErrorData;
+#[deprecated(
+    note = "Use `rmcp::ErrorData` instead, `rmcp::ErrorData` could become `RmcpError` in the future."
+)]
 pub type Error = ErrorData;
-
 impl Display for ErrorData {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}: {}", self.code.0, self.message)?;
@@ -15,3 +17,40 @@ impl Display for ErrorData {
 }
 
 impl std::error::Error for ErrorData {}
+
+/// This is an unified error type for the errors could be returned by the service.
+#[derive(Debug, thiserror::Error)]
+pub enum RmcpError {
+    #[error("Service error: {0}")]
+    Service(#[from] ServiceError),
+    #[cfg(feature = "client")]
+    #[error("Client initialization error: {0}")]
+    ClientInitialize(#[from] crate::service::ClientInitializeError),
+    #[cfg(feature = "server")]
+    #[error("Server initialization error: {0}")]
+    ServerInitialize(#[from] crate::service::ServerInitializeError),
+    #[error("Runtime error: {0}")]
+    Runtime(#[from] tokio::task::JoinError),
+    #[error("Transport creation error: {error}")]
+    // TODO: Maybe we can introduce something like `TryIntoTransport` to auto wrap transport type,
+    // but it could be an breaking change, so we could do it in the future.
+    TransportCreation {
+        into_transport_type_name: Cow<'static, str>,
+        into_transport_type_id: std::any::TypeId,
+        #[source]
+        error: Box<dyn std::error::Error + Send + Sync>,
+    },
+    // and cancellation shouldn't be an error?
+}
+
+impl RmcpError {
+    pub fn transport_creation<T: 'static>(
+        error: impl Into<Box<dyn std::error::Error + Send + Sync>>,
+    ) -> Self {
+        RmcpError::TransportCreation {
+            into_transport_type_id: std::any::TypeId::of::<T>(),
+            into_transport_type_name: std::any::type_name::<T>().into(),
+            error: error.into(),
+        }
+    }
+}

crates/rmcp/src/handler/client.rs

@@ -1,6 +1,6 @@
 pub mod progress;
 use crate::{
-    error::Error as McpError,
+    error::ErrorData as McpError,
     model::*,
     service::{NotificationContext, RequestContext, RoleClient, Service, ServiceRole},
 };

crates/rmcp/src/handler/server.rs

@@ -1,5 +1,5 @@
 use crate::{
-    error::Error as McpError,
+    error::ErrorData as McpError,
     model::*,
     service::{NotificationContext, RequestContext, RoleServer, Service, ServiceRole},
 };

crates/rmcp/src/handler/server/router.rs

@@ -51,7 +51,7 @@ where
         &self,
         notification: <RoleServer as crate::service::ServiceRole>::PeerNot,
         context: NotificationContext<RoleServer>,
-    ) -> Result<(), crate::Error> {
+    ) -> Result<(), crate::ErrorData> {
         self.service
             .handle_notification(notification, context)
             .await
@@ -60,7 +60,7 @@ where
         &self,
         request: <RoleServer as crate::service::ServiceRole>::PeerReq,
         context: crate::service::RequestContext<RoleServer>,
-    ) -> Result<<RoleServer as crate::service::ServiceRole>::Resp, crate::Error> {
+    ) -> Result<<RoleServer as crate::service::ServiceRole>::Resp, crate::ErrorData> {
         match request {
             ClientRequest::CallToolRequest(request) => {
                 if self.tool_router.has_route(request.params.name.as_ref())

crates/rmcp/src/handler/server/router/tool.rs

@@ -52,7 +52,7 @@ impl<S: Send + Sync + 'static> ToolRoute<S> {
     where
         C: for<'a> Fn(
                 ToolCallContext<'a, S>,
-            ) -> BoxFuture<'a, Result<CallToolResult, crate::Error>>
+            ) -> BoxFuture<'a, Result<CallToolResult, crate::ErrorData>>
             + Send
             + Sync
             + 'static,
@@ -237,11 +237,11 @@ where
     pub async fn call(
         &self,
         context: ToolCallContext<'_, S>,
-    ) -> Result<CallToolResult, crate::Error> {
+    ) -> Result<CallToolResult, crate::ErrorData> {
         let item = self
             .map
             .get(context.name())
-            .ok_or_else(|| crate::Error::invalid_params("tool not found", None))?;
+            .ok_or_else(|| crate::ErrorData::invalid_params("tool not found", None))?;
         (item.call)(context).await
     }