mcp_runner/
error.rs

1/// Error handling module for MCP Runner.
2///
3/// This module defines the error types used throughout the library.
4/// It provides a comprehensive set of errors that can occur when
5/// working with MCP servers, along with helpful context for debugging.
6///
7/// # Example
8///
9/// ```
10/// use mcp_runner::{McpRunner, error::{Error, Result}};
11///
12/// fn handle_error(result: Result<()>) {
13///     match result {
14///         Ok(_) => println!("Operation succeeded"),
15///         Err(Error::ServerNotFound(name)) => println!("Server '{}' not found in configuration", name),
16///         Err(Error::Communication(msg)) => println!("Communication error: {}", msg),
17///         Err(Error::Timeout(msg)) => println!("Operation timed out: {}", msg),
18///         Err(e) => println!("Other error: {}", e),
19///     }
20/// }
21/// ```
22use thiserror::Error;
23
24/// Errors that can occur in the mcp-runner library.
25///
26/// This enum represents all possible error types that can be returned from
27/// operations in the MCP Runner library. Each variant includes context
28/// information to help diagnose and handle the error appropriately.
29#[derive(Error, Debug)]
30pub enum Error {
31    /// Indicates an underlying IO error occurred.
32    ///
33    /// This typically happens when:
34    /// - Reading from or writing to files
35    /// - Reading from or writing to process stdin/stdout
36    /// - Network operations
37    #[error("IO error: {0}")]
38    Io(#[from] std::io::Error),
39
40    /// Failed to parse configuration from a file or string.
41    ///
42    /// This error occurs when:
43    /// - The configuration JSON is malformed
44    /// - Required fields are missing
45    /// - Field types are incorrect
46    #[error("Failed to parse configuration: {0}")]
47    ConfigParse(String),
48
49    /// Configuration is valid JSON but contains invalid values.
50    ///
51    /// This error occurs when:
52    /// - A command doesn't exist or isn't executable
53    /// - Environment variables have invalid values
54    /// - Conflicting settings are specified
55    #[error("Invalid configuration: {0}")]
56    ConfigInvalid(String),
57
58    /// Error when starting, stopping, or communicating with a server process.
59    ///
60    /// This error occurs when:
61    /// - The process fails to start
62    /// - The process exits unexpectedly
63    /// - The process fails to respond correctly
64    #[error("Server process error: {0}")]
65    Process(String),
66
67    /// Error in the JSON-RPC protocol.
68    ///
69    /// This error occurs when:
70    /// - The server returns an error response
71    /// - The method doesn't exist
72    /// - Invalid parameters are provided
73    /// - The server response doesn't match the request
74    #[error("JSON-RPC error: {0}")]
75    JsonRpc(String),
76
77    /// Error in the transport layer.
78    ///
79    /// This error occurs when:
80    /// - The transport fails to initialize
81    /// - The transport encounters an error during operation
82    /// - The transport fails to close properly
83    #[error("Transport error: {0}")]
84    Transport(String),
85
86    /// Requested server was not found in the configuration.
87    ///
88    /// This error occurs when:
89    /// - A server name is passed that doesn't exist in the config
90    /// - A server ID is used that doesn't match any running server
91    #[error("Server not found: {0}")]
92    ServerNotFound(String),
93
94    /// Requested tool was not found on the MCP server.
95    ///
96    /// This error occurs when:
97    /// - The tool name doesn't exist on the server
98    /// - The tool is disabled or unavailable
99    #[error("Tool not found: {0}")]
100    ToolNotFound(String),
101
102    /// Requested resource was not found on the MCP server.
103    ///
104    /// This error occurs when:
105    /// - The resource URI doesn't exist
106    /// - The resource is not accessible to the client
107    #[error("Resource not found: {0}")]
108    ResourceNotFound(String),
109
110    /// Error in communication with the MCP server.
111    ///
112    /// This error occurs when:
113    /// - The server doesn't respond
114    /// - The response is malformed
115    /// - The connection is lost
116    #[error("Communication error: {0}")]
117    Communication(String),
118
119    /// Operation timed out.
120    ///
121    /// This error occurs when:
122    /// - A server takes too long to start
123    /// - A server takes too long to respond
124    /// - A response is expected but doesn't arrive within the timeout period
125    #[error("Timeout: {0}")]
126    Timeout(String),
127
128    /// The server is already running.
129    ///
130    /// This error occurs when:
131    /// - Attempting to start a server that's already running
132    #[error("Already running")]
133    AlreadyRunning,
134
135    /// The server is not running.
136    ///
137    /// This error occurs when:
138    /// - Attempting to stop a server that's not running
139    /// - Attempting to get a client for a server that's not running
140    #[error("Not running")]
141    NotRunning,
142
143    /// Error in serializing or deserializing data.
144    ///
145    /// This error occurs when:
146    /// - Arguments can't be serialized to JSON
147    /// - Results can't be deserialized from JSON
148    /// - Types don't match expected schema
149    #[error("Serialization error: {0}")]
150    Serialization(String),
151
152    /// Any other error not covered by the above categories.
153    ///
154    /// This is a catch-all error for cases not explicitly handled elsewhere.
155    #[error("Other error: {0}")]
156    Other(String),
157}
158
159/// Result type for mcp-runner operations.
160///
161/// This is a convenience type alias for `std::result::Result` with the `Error` type
162/// from this module. Use this throughout the library and in client code to handle
163/// errors in a consistent way.
164pub type Result<T> = std::result::Result<T, Error>;
mcp_runner/error.rs

mcp_runner/
error.rs
