pulseengine_mcp_cli/
lib.rs

1//! CLI integration and configuration framework for MCP servers
2//!
3//! This crate provides automatic CLI generation, configuration management, and server setup
4//! for MCP servers. It eliminates boilerplate code and provides a modern, ergonomic API.
5//!
6//! # Features
7//!
8//! - **Automatic CLI Generation**: Generate command-line interfaces from configuration structs
9//! - **Configuration Management**: Type-safe configuration with environment variable support
10//! - **Server Integration**: Seamless integration with the MCP server framework
11//! - **Logging Setup**: Built-in structured logging configuration
12//! - **Builder Patterns**: Fluent APIs for server configuration
13//!
14//! # Quick Start
15//!
16//! ```rust,ignore
17//! use pulseengine_mcp_cli::{McpConfig, DefaultLoggingConfig};
18//! use pulseengine_mcp_protocol::ServerInfo;
19//! use clap::Parser;
20//!
21//! #[derive(McpConfig, Parser)]
22//! struct MyServerConfig {
23//!     #[clap(short, long, default_value = "8080")]
24//!     port: u16,
25//!
26//!     #[clap(short, long)]
27//!     database_url: String,
28//!
29//!     #[mcp(auto_populate)]
30//!     #[clap(skip)]
31//!     server_info: Option<ServerInfo>,
32//!
33//!     #[mcp(logging)]
34//!     #[clap(skip)]
35//!     logging: Option<DefaultLoggingConfig>,
36//! }
37//!
38//! #[tokio::main]
39//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
40//!     let config = MyServerConfig::parse();
41//!     config.initialize_logging()?;
42//!     // Use server_builder() for advanced configuration
43//!     Ok(())
44//! }
45//! ```
46
47use thiserror::Error;
48
49/// Re-export commonly used types
50pub use pulseengine_mcp_protocol::*;
51
52#[cfg(feature = "cli")]
53pub use clap;
54
55/// Error types for CLI operations
56#[derive(Debug, Error)]
57pub enum CliError {
58    #[error("Configuration error: {0}")]
59    Configuration(String),
60
61    #[error("CLI parsing error: {0}")]
62    Parsing(String),
63
64    #[error("Server setup error: {0}")]
65    ServerSetup(String),
66
67    #[error("Logging setup error: {0}")]
68    Logging(String),
69
70    #[error("I/O error: {0}")]
71    Io(#[from] std::io::Error),
72
73    #[error("Protocol error: {0}")]
74    Protocol(#[from] pulseengine_mcp_protocol::Error),
75}
76
77impl CliError {
78    pub fn configuration(msg: impl Into<String>) -> Self {
79        Self::Configuration(msg.into())
80    }
81
82    pub fn parsing(msg: impl Into<String>) -> Self {
83        Self::Parsing(msg.into())
84    }
85
86    pub fn server_setup(msg: impl Into<String>) -> Self {
87        Self::ServerSetup(msg.into())
88    }
89
90    pub fn logging(msg: impl Into<String>) -> Self {
91        Self::Logging(msg.into())
92    }
93}
94
95/// Configuration trait for MCP servers
96pub trait McpConfiguration: Sized {
97    /// Initialize logging from configuration
98    fn initialize_logging(&self) -> std::result::Result<(), CliError>;
99
100    /// Get server information
101    fn get_server_info(&self) -> &ServerInfo;
102
103    /// Get logging configuration
104    fn get_logging_config(&self) -> &DefaultLoggingConfig;
105
106    /// Validate the configuration
107    fn validate(&self) -> std::result::Result<(), CliError> {
108        Ok(())
109    }
110}
111
112// Re-export proc macros when derive feature is enabled
113#[cfg(feature = "derive")]
114pub use pulseengine_mcp_cli_derive::{McpBackend, McpConfig};
115
116// Modules
117pub mod config;
118pub mod server;
119pub mod utils;
120
121// Test modules
122#[cfg(test)]
123mod config_tests;
124#[cfg(test)]
125mod lib_tests;
126#[cfg(test)]
127mod utils_tests;
128
129// Re-export main types
130pub use config::*;
131pub use server::*;