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::*;