diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 47c7de85..25cddd5b 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -21,7 +21,9 @@ "Bash(grep:*)", "Bash(gh pr checks:*)", "Bash(find:*)", - "Bash(cargo:*)" + "Bash(cargo:*)", + "WebFetch(domain:doc.rust-lang.org)", + "WebFetch(domain:forge.rust-lang.org)" ], "deny": [] } diff --git a/.github/workflows/code-coverage.yml b/.github/workflows/code-coverage.yml index c811bf20..b09d4a0a 100644 --- a/.github/workflows/code-coverage.yml +++ b/.github/workflows/code-coverage.yml @@ -33,7 +33,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 with: components: llvm-tools-preview @@ -55,9 +55,9 @@ jobs: ~/.cargo/registry ~/.cargo/git target - key: ${{ runner.os }}-cargo-coverage-1.85-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }} + key: ${{ runner.os }}-cargo-coverage-1.88-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }} restore-keys: | - ${{ runner.os }}-cargo-coverage-1.85- + ${{ runner.os }}-cargo-coverage-1.88- ${{ runner.os }}-cargo- - name: Generate code coverage diff --git a/.github/workflows/docker-validation.yml b/.github/workflows/docker-validation.yml index 6716a25f..2f9ff4c9 100644 --- a/.github/workflows/docker-validation.yml +++ b/.github/workflows/docker-validation.yml @@ -113,7 +113,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Clean stale artifacts run: | diff --git a/.github/workflows/external-validation.yml b/.github/workflows/external-validation.yml index 5c5d09bb..8b138496 100644 --- a/.github/workflows/external-validation.yml +++ b/.github/workflows/external-validation.yml @@ -52,7 +52,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Setup Python uses: actions/setup-python@v5 @@ -66,9 +66,9 @@ jobs: ~/.cargo/registry ~/.cargo/git target - key: ${{ runner.os }}-cargo-external-release-1.85-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }} + key: ${{ runner.os }}-cargo-external-release-1.88-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }} restore-keys: | - ${{ runner.os }}-cargo-external-1.85- + ${{ runner.os }}-cargo-external-1.88- ${{ runner.os }}-cargo- - name: Cache Python dependencies @@ -167,7 +167,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Setup Python uses: actions/setup-python@v5 @@ -205,7 +205,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Build validation tools run: cargo build --package pulseengine-mcp-external-validation --features "proptest,fuzzing" --release @@ -241,7 +241,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Run cargo audit run: | @@ -270,7 +270,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Run benchmarks run: | diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index 38db9d93..00035ad0 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -48,7 +48,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 with: components: rustfmt, clippy @@ -68,9 +68,9 @@ jobs: ~/.cargo/registry ~/.cargo/git target - key: ${{ runner.os }}-cargo-pr-release-1.85-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }} + key: ${{ runner.os }}-cargo-pr-release-1.88-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }} restore-keys: | - ${{ runner.os }}-cargo-pr-1.82- + ${{ runner.os }}-cargo-pr-1.88- ${{ runner.os }}-cargo- - name: Check formatting @@ -121,7 +121,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Setup Python uses: actions/setup-python@v5 @@ -159,7 +159,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Rust - uses: dtolnay/rust-toolchain@1.85 + uses: dtolnay/rust-toolchain@1.88 - name: Test validation tool CLI run: | diff --git a/.gitignore b/.gitignore index 0c069f29..121c231c 100644 --- a/.gitignore +++ b/.gitignore @@ -37,4 +37,4 @@ cobertura.xml lcov.info lcov-*.info coverage-summary.txt -/target/llvm-cov/ \ No newline at end of file +/target/llvm-cov/.claude/ diff --git a/Cargo.lock b/Cargo.lock index c58bb6f1..3f668ee6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1149,6 +1149,7 @@ name = "hello-world-macros" version = "0.1.0" dependencies = [ "async-trait", + "chrono", "pulseengine-mcp-auth", "pulseengine-mcp-macros", "pulseengine-mcp-protocol", @@ -2283,7 +2284,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-auth" -version = "0.6.0" +version = "0.7.0" dependencies = [ "aes-gcm", "anyhow", @@ -2322,7 +2323,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-cli" -version = "0.6.0" +version = "0.7.0" dependencies = [ "clap", "pulseengine-mcp-cli-derive", @@ -2341,7 +2342,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-cli-derive" -version = "0.6.0" +version = "0.7.0" dependencies = [ "async-trait", "clap", @@ -2359,7 +2360,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-external-validation" -version = "0.6.0" +version = "0.7.0" dependencies = [ "anyhow", "arbitrary", @@ -2397,7 +2398,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-integration-tests" -version = "0.6.0" +version = "0.7.0" dependencies = [ "anyhow", "assert_matches", @@ -2425,7 +2426,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-logging" -version = "0.6.0" +version = "0.7.0" dependencies = [ "chrono", "hex", @@ -2444,7 +2445,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-macros" -version = "0.6.0" +version = "0.7.0" dependencies = [ "async-trait", "darling", @@ -2467,7 +2468,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-monitoring" -version = "0.6.0" +version = "0.7.0" dependencies = [ "anyhow", "chrono", @@ -2487,7 +2488,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-protocol" -version = "0.6.0" +version = "0.7.0" dependencies = [ "async-trait", "chrono", @@ -2503,7 +2504,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-security" -version = "0.6.0" +version = "0.7.0" dependencies = [ "anyhow", "async-trait", @@ -2525,7 +2526,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-server" -version = "0.6.0" +version = "0.7.0" dependencies = [ "anyhow", "async-trait", @@ -2552,7 +2553,7 @@ dependencies = [ [[package]] name = "pulseengine-mcp-transport" -version = "0.6.0" +version = "0.7.0" dependencies = [ "anyhow", "async-stream", diff --git a/Cargo.toml b/Cargo.toml index cff85dc7..6fb65e61 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -27,9 +27,9 @@ members = [ resolver = "2" [workspace.package] -version = "0.6.0" -rust-version = "1.85" -edition = "2021" +version = "0.7.0" +rust-version = "1.88" +edition = "2024" license = "MIT OR Apache-2.0" authors = ["PulseEngine Contributors"] repository = "https://github.com/pulseengine/mcp" @@ -101,17 +101,17 @@ assert_matches = "1.5" serde_yaml = "0.9" # Framework internal dependencies (published versions) -pulseengine-mcp-protocol = { version = "0.6.0", path = "mcp-protocol" } -pulseengine-mcp-logging = { version = "0.6.0", path = "mcp-logging" } -pulseengine-mcp-auth = { version = "0.6.0", path = "mcp-auth" } -pulseengine-mcp-security = { version = "0.6.0", path = "mcp-security" } -pulseengine-mcp-monitoring = { version = "0.6.0", path = "mcp-monitoring" } -pulseengine-mcp-transport = { version = "0.6.0", path = "mcp-transport" } -pulseengine-mcp-cli = { version = "0.6.0", path = "mcp-cli" } -pulseengine-mcp-cli-derive = { version = "0.6.0", path = "mcp-cli-derive" } -pulseengine-mcp-server = { version = "0.6.0", path = "mcp-server" } -pulseengine-mcp-macros = { version = "0.6.0", path = "mcp-macros" } -pulseengine-mcp-external-validation = { version = "0.6.0", path = "mcp-external-validation" } +pulseengine-mcp-protocol = { version = "0.7.0", path = "mcp-protocol" } +pulseengine-mcp-logging = { version = "0.7.0", path = "mcp-logging" } +pulseengine-mcp-auth = { version = "0.7.0", path = "mcp-auth" } +pulseengine-mcp-security = { version = "0.7.0", path = "mcp-security" } +pulseengine-mcp-monitoring = { version = "0.7.0", path = "mcp-monitoring" } +pulseengine-mcp-transport = { version = "0.7.0", path = "mcp-transport" } +pulseengine-mcp-cli = { version = "0.7.0", path = "mcp-cli" } +pulseengine-mcp-cli-derive = { version = "0.7.0", path = "mcp-cli-derive" } +pulseengine-mcp-server = { version = "0.7.0", path = "mcp-server" } +pulseengine-mcp-macros = { version = "0.7.0", path = "mcp-macros" } +pulseengine-mcp-external-validation = { version = "0.7.0", path = "mcp-external-validation" } [profile.release] opt-level = "s" diff --git a/docs/ADVANCED_PATTERNS.md b/docs/ADVANCED_PATTERNS.md new file mode 100644 index 00000000..8d215ee1 --- /dev/null +++ b/docs/ADVANCED_PATTERNS.md @@ -0,0 +1,870 @@ +# PulseEngine MCP Macros: Advanced Patterns + +This guide covers advanced implementation patterns for building sophisticated MCP servers with PulseEngine macros. + +## Architectural Patterns + +### Layered Server Architecture + +Structure complex servers with clear separation of concerns: + +```rust +use pulseengine_mcp_macros::{mcp_server, mcp_tool, mcp_resource}; +use std::sync::Arc; + +// Data layer +#[derive(Clone)] +pub struct DataLayer { + database: Arc, + cache: Arc, +} + +// Business logic layer +#[derive(Clone)] +pub struct BusinessLayer { + data: DataLayer, + validator: Arc, + notifier: Arc, +} + +// Presentation layer (MCP Server) +#[mcp_server( + name = "Enterprise Application Server", + app_name = "enterprise-app", + version = "3.0.0" +)] +#[derive(Clone)] +pub struct EnterpriseServer { + business: BusinessLayer, + security: Arc, + metrics: Arc, +} + +#[mcp_tool] +impl EnterpriseServer { + /// High-level business operation + async fn process_business_transaction(&self, request: TransactionRequest) -> Result { + // Security check + self.security.validate_request(&request).await?; + + // Metrics + let _timer = self.metrics.start_timer("transaction_processing"); + + // Business logic + let result = self.business.process_transaction(request).await?; + + // Notification + self.business.notifier.notify_transaction_complete(&result).await?; + + Ok(result) + } +} +``` + +### Plugin Architecture + +Build extensible servers with dynamic capability loading: + +```rust +use async_trait::async_trait; + +#[async_trait] +pub trait ServerPlugin: Send + Sync { + fn name(&self) -> &str; + fn version(&self) -> &str; + async fn initialize(&self, context: &PluginContext) -> Result<(), PluginError>; + async fn handle_request(&self, request: PluginRequest) -> Result; +} + +#[mcp_server(name = "Plugin-Based Server")] +#[derive(Clone)] +pub struct PluginServer { + plugins: Arc>>>, + context: Arc, +} + +impl PluginServer { + pub async fn register_plugin(&self, plugin: Box) -> Result<(), PluginError> { + let name = plugin.name().to_string(); + plugin.initialize(&self.context).await?; + + let mut plugins = self.plugins.write().await; + plugins.insert(name, plugin); + Ok(()) + } +} + +#[mcp_tool] +impl PluginServer { + /// Execute plugin operation + async fn execute_plugin(&self, plugin_name: String, request: serde_json::Value) -> Result { + let plugins = self.plugins.read().await; + let plugin = plugins.get(&plugin_name) + .ok_or(PluginError::NotFound { name: plugin_name })?; + + let plugin_request = PluginRequest::from_json(request)?; + let response = plugin.handle_request(plugin_request).await?; + + Ok(response.to_json()) + } +} +``` + +## State Management Patterns + +### Event Sourcing + +Implement event sourcing for audit trails and state reconstruction: + +```rust +use serde::{Deserialize, Serialize}; +use chrono::{DateTime, Utc}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Event { + pub id: uuid::Uuid, + pub aggregate_id: String, + pub event_type: String, + pub data: serde_json::Value, + pub timestamp: DateTime, + pub version: u64, +} + +#[derive(Clone)] +pub struct EventStore { + storage: Arc, + publishers: Arc>>>, +} + +impl EventStore { + pub async fn append_event(&self, event: Event) -> Result<(), EventError> { + // Store event + self.storage.append(&event).await?; + + // Publish to subscribers + let publishers = self.publishers.read().await; + for publisher in publishers.iter() { + let _ = publisher.publish(&event).await; // Don't fail on publish errors + } + + Ok(()) + } + + pub async fn get_events(&self, aggregate_id: &str, from_version: Option) -> Result, EventError> { + self.storage.get_events(aggregate_id, from_version).await + } +} + +#[mcp_server(name = "Event Sourced Server")] +#[derive(Clone)] +pub struct EventSourcedServer { + event_store: EventStore, + projections: Arc>>>, +} + +#[mcp_tool] +impl EventSourcedServer { + /// Execute command and store events + async fn execute_command(&self, command: Command) -> Result { + // Validate command + command.validate()?; + + // Generate events + let events = command.to_events()?; + + // Store events + for event in events { + self.event_store.append_event(event).await?; + } + + Ok(CommandResult::Success { id: command.id }) + } + + /// Query projection + async fn query_projection(&self, projection_name: String, query: serde_json::Value) -> Result { + let projections = self.projections.read().await; + let projection = projections.get(&projection_name) + .ok_or(QueryError::ProjectionNotFound { name: projection_name })?; + + projection.query(query).await + } +} + +#[mcp_resource(uri_template = "events://{aggregate_id}")] +impl EventSourcedServer { + /// Get event stream for aggregate + async fn event_stream(&self, aggregate_id: String) -> Result, EventError> { + self.event_store.get_events(&aggregate_id, None).await + } +} +``` + +### CQRS (Command Query Responsibility Segregation) + +Separate read and write operations for optimal performance: + +```rust +// Command side - Write operations +#[derive(Clone)] +pub struct CommandProcessor { + event_store: EventStore, + domain_services: Arc, +} + +impl CommandProcessor { + pub async fn handle(&self, command: C) -> Result { + let aggregate = self.load_aggregate(&command.aggregate_id()).await?; + let events = aggregate.handle_command(command, &self.domain_services).await?; + + for event in events { + self.event_store.append_event(event).await?; + } + + Ok(CommandResult::Success) + } +} + +// Query side - Read operations +#[derive(Clone)] +pub struct QueryProcessor { + read_store: Arc, + cache: Arc, +} + +impl QueryProcessor { + pub async fn handle(&self, query: Q) -> Result { + // Check cache first + if let Some(cached) = self.cache.get(&query.cache_key()).await? { + return Ok(cached); + } + + // Execute query + let result = self.read_store.execute_query(query).await?; + + // Cache result + self.cache.set(&query.cache_key(), &result, query.cache_duration()).await?; + + Ok(result) + } +} + +#[mcp_server(name = "CQRS Server")] +#[derive(Clone)] +pub struct CqrsServer { + command_processor: CommandProcessor, + query_processor: QueryProcessor, +} + +#[mcp_tool] +impl CqrsServer { + /// Execute write command + async fn execute_command(&self, command_type: String, payload: serde_json::Value) -> Result { + match command_type.as_str() { + "create_user" => { + let cmd: CreateUserCommand = serde_json::from_value(payload)?; + self.command_processor.handle(cmd).await + } + "update_user" => { + let cmd: UpdateUserCommand = serde_json::from_value(payload)?; + self.command_processor.handle(cmd).await + } + _ => Err(CommandError::UnknownCommand { command_type }) + } + } + + /// Execute read query + async fn execute_query(&self, query_type: String, payload: serde_json::Value) -> Result { + match query_type.as_str() { + "get_user" => { + let query: GetUserQuery = serde_json::from_value(payload)?; + let result = self.query_processor.handle(query).await?; + Ok(serde_json::to_value(result)?) + } + "list_users" => { + let query: ListUsersQuery = serde_json::from_value(payload)?; + let result = self.query_processor.handle(query).await?; + Ok(serde_json::to_value(result)?) + } + _ => Err(QueryError::UnknownQuery { query_type }) + } + } +} +``` + +## Security Patterns + +### Role-Based Access Control (RBAC) + +Implement fine-grained access control: + +```rust +use std::collections::HashSet; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct User { + pub id: String, + pub roles: HashSet, + pub permissions: HashSet, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct AccessContext { + pub user: User, + pub resource: String, + pub action: String, + pub environment: HashMap, +} + +pub struct AccessControlManager { + policies: Arc>>, + role_permissions: Arc>>>, +} + +impl AccessControlManager { + pub async fn check_access(&self, context: &AccessContext) -> Result { + // Check direct permissions + let required_permission = format!("{}:{}", context.resource, context.action); + if context.user.permissions.contains(&required_permission) { + return Ok(true); + } + + // Check role-based permissions + let role_perms = self.role_permissions.read().await; + for role in &context.user.roles { + if let Some(permissions) = role_perms.get(role) { + if permissions.contains(&required_permission) { + return Ok(true); + } + } + } + + // Check policies + let policies = self.policies.read().await; + for policy in policies.values() { + if policy.applies_to(context) && policy.evaluate(context).await? { + return Ok(true); + } + } + + Ok(false) + } +} + +#[mcp_server(name = "Secure Server")] +#[derive(Clone)] +pub struct SecureServer { + access_control: AccessControlManager, + audit_logger: Arc, +} + +// Custom macro for access control +macro_rules! require_permission { + ($server:expr, $user:expr, $resource:expr, $action:expr) => { + { + let context = AccessContext { + user: $user.clone(), + resource: $resource.to_string(), + action: $action.to_string(), + environment: std::collections::HashMap::new(), + }; + + if !$server.access_control.check_access(&context).await? { + $server.audit_logger.log_access_denied(&context).await; + return Err(SecurityError::AccessDenied { + resource: $resource.to_string(), + action: $action.to_string() + }); + } + + $server.audit_logger.log_access_granted(&context).await; + } + }; +} + +#[mcp_tool] +impl SecureServer { + /// Secure operation with access control + async fn secure_operation(&self, user_id: String, resource_id: String, data: serde_json::Value) -> Result { + // Get user context + let user = self.get_user(&user_id).await?; + + // Check permissions + require_permission!(self, user, "resource", "modify"); + + // Perform operation + let result = format!("Modified resource {} with data", resource_id); + + Ok(result) + } +} +``` + +### Input Validation and Sanitization + +Comprehensive input validation framework: + +```rust +use validator::{Validate, ValidationError, ValidationErrors}; +use regex::Regex; + +#[derive(Debug, Clone)] +pub struct ValidationRules { + pub max_length: Option, + pub min_length: Option, + pub pattern: Option, + pub allowed_values: Option>, + pub custom_validators: Vec Result<(), ValidationError>>, +} + +pub struct InputValidator { + rules: HashMap, + sanitizers: HashMap String>, +} + +impl InputValidator { + pub fn validate_field(&self, field_name: &str, value: &str) -> Result { + let mut errors = ValidationErrors::new(); + + if let Some(rules) = self.rules.get(field_name) { + // Length validation + if let Some(max_len) = rules.max_length { + if value.len() > max_len { + errors.add(field_name, ValidationError::new("max_length")); + } + } + + if let Some(min_len) = rules.min_length { + if value.len() < min_len { + errors.add(field_name, ValidationError::new("min_length")); + } + } + + // Pattern validation + if let Some(pattern) = &rules.pattern { + if !pattern.is_match(value) { + errors.add(field_name, ValidationError::new("pattern")); + } + } + + // Allowed values + if let Some(allowed) = &rules.allowed_values { + if !allowed.contains(value) { + errors.add(field_name, ValidationError::new("allowed_values")); + } + } + + // Custom validators + for validator in &rules.custom_validators { + if let Err(e) = validator(value) { + errors.add(field_name, e); + } + } + } + + if errors.is_empty() { + // Apply sanitization + let sanitized = if let Some(sanitizer) = self.sanitizers.get(field_name) { + sanitizer(value) + } else { + value.to_string() + }; + Ok(sanitized) + } else { + Err(errors) + } + } +} + +#[derive(Debug, Validate, Deserialize)] +pub struct UserInput { + #[validate(length(min = 1, max = 100))] + #[validate(regex = "USERNAME_REGEX")] + pub username: String, + + #[validate(email)] + pub email: String, + + #[validate(length(min = 8, max = 128))] + pub password: String, + + #[validate(range(min = 18, max = 120))] + pub age: Option, +} + +#[mcp_server(name = "Validated Server")] +#[derive(Clone)] +pub struct ValidatedServer { + validator: Arc, +} + +#[mcp_tool] +impl ValidatedServer { + /// Create user with comprehensive validation + async fn create_user(&self, input: UserInput) -> Result { + // Built-in validation + input.validate()?; + + // Custom validation + let username = self.validator.validate_field("username", &input.username)?; + let email = self.validator.validate_field("email", &input.email)?; + + // Security checks + self.check_password_strength(&input.password).await?; + self.check_email_domain(&email).await?; + + // Create user + Ok(User { + id: uuid::Uuid::new_v4().to_string(), + username, + email, + created_at: chrono::Utc::now(), + }) + } +} +``` + +## Performance Patterns + +### Connection Pooling and Resource Management + +Efficient resource management for high-performance applications: + +```rust +use deadpool_postgres::{Pool, PoolError}; +use deadpool_redis::{Pool as RedisPool, redis::RedisError}; + +#[derive(Clone)] +pub struct ResourceManager { + db_pool: Pool, + redis_pool: RedisPool, + http_client: Arc, + metrics: Arc, +} + +impl ResourceManager { + pub async fn new(config: &ResourceConfig) -> Result { + // Database pool + let mut db_config = deadpool_postgres::Config::new(); + db_config.host = Some(config.db_host.clone()); + db_config.user = Some(config.db_user.clone()); + db_config.password = Some(config.db_password.clone()); + db_config.dbname = Some(config.db_name.clone()); + let db_pool = db_config.create_pool(Some(deadpool_postgres::Runtime::Tokio1), tokio_postgres::NoTls)?; + + // Redis pool + let redis_config = deadpool_redis::Config::from_url(&config.redis_url); + let redis_pool = redis_config.create_pool(Some(deadpool_redis::Runtime::Tokio1))?; + + // HTTP client with connection pooling + let http_client = Arc::new( + reqwest::Client::builder() + .pool_max_idle_per_host(config.http_pool_size) + .timeout(config.http_timeout) + .build()? + ); + + Ok(Self { + db_pool, + redis_pool, + http_client, + metrics: Arc::new(MetricsRegistry::new()), + }) + } + + pub async fn with_db_transaction(&self, f: F) -> Result + where + F: FnOnce(deadpool_postgres::Transaction<'_>) -> BoxFuture<'_, Result>, + E: From, + { + let client = self.db_pool.get().await?; + let transaction = client.transaction().await?; + let result = f(transaction).await; + // Transaction is automatically committed or rolled back + result + } +} + +#[mcp_server(name = "High Performance Server")] +#[derive(Clone)] +pub struct HighPerformanceServer { + resources: ResourceManager, + cache: Arc, +} + +#[mcp_tool] +impl HighPerformanceServer { + /// High-performance data operation with caching + async fn get_user_data(&self, user_id: String) -> Result { + let cache_key = format!("user_data:{}", user_id); + + // L1 Cache (in-memory) + if let Some(data) = self.cache.get_l1(&cache_key).await { + self.resources.metrics.increment_counter("cache.l1.hit"); + return Ok(data); + } + + // L2 Cache (Redis) + if let Some(data) = self.cache.get_l2(&cache_key).await? { + self.resources.metrics.increment_counter("cache.l2.hit"); + // Populate L1 cache + self.cache.set_l1(&cache_key, &data, Duration::from_secs(300)).await; + return Ok(data); + } + + // Database + self.resources.metrics.increment_counter("database.query"); + let data = self.resources.with_db_transaction(|tx| { + Box::pin(async move { + let row = tx.query_one("SELECT * FROM users WHERE id = $1", &[&user_id]).await?; + Ok(UserData::from_row(row)) + }) + }).await?; + + // Populate caches + self.cache.set_l2(&cache_key, &data, Duration::from_secs(3600)).await?; + self.cache.set_l1(&cache_key, &data, Duration::from_secs(300)).await; + + Ok(data) + } +} +``` + +### Batch Processing and Streaming + +Handle large datasets efficiently: + +```rust +use futures::{Stream, StreamExt, TryStreamExt}; +use tokio::sync::mpsc; + +#[derive(Clone)] +pub struct BatchProcessor { + batch_size: usize, + flush_interval: Duration, + processor: Arc) -> BoxFuture<'_, Result<(), ProcessingError>> + Send + Sync>, +} + +impl BatchProcessor { + pub async fn process_stream(&self, mut stream: S) -> Result<(), ProcessingError> + where + S: Stream> + Unpin, + { + let mut batch = Vec::with_capacity(self.batch_size); + let mut flush_interval = tokio::time::interval(self.flush_interval); + + loop { + tokio::select! { + item = stream.try_next() => { + match item? { + Some(item) => { + batch.push(item); + if batch.len() >= self.batch_size { + (self.processor)(std::mem::take(&mut batch)).await?; + } + } + None => break, // Stream ended + } + } + _ = flush_interval.tick() => { + if !batch.is_empty() { + (self.processor)(std::mem::take(&mut batch)).await?; + } + } + } + } + + // Process remaining items + if !batch.is_empty() { + (self.processor)(batch).await?; + } + + Ok(()) + } +} + +#[mcp_server(name = "Streaming Server")] +#[derive(Clone)] +pub struct StreamingServer { + batch_processor: BatchProcessor, + stream_manager: Arc, +} + +#[mcp_tool] +impl StreamingServer { + /// Process large dataset with streaming + async fn process_large_dataset(&self, dataset_id: String, chunk_size: Option) -> Result { + let chunk_size = chunk_size.unwrap_or(1000); + + // Create data stream + let stream = self.stream_manager.create_data_stream(&dataset_id, chunk_size).await?; + + // Process in background + let processor = self.batch_processor.clone(); + let processing_id = uuid::Uuid::new_v4().to_string(); + + tokio::spawn(async move { + if let Err(e) = processor.process_stream(stream).await { + eprintln!("Processing failed: {}", e); + } + }); + + Ok(ProcessingStatus { + id: processing_id, + status: "started".to_string(), + estimated_duration: Some(Duration::from_secs(300)), + }) + } +} + +#[mcp_resource(uri_template = "stream://{stream_id}")] +impl StreamingServer { + /// Access streaming data resource + async fn stream_resource(&self, stream_id: String) -> Result>, std::io::Error> { + let stream = self.stream_manager.get_stream(&stream_id).await + .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "Stream not found"))?; + + Ok(stream.map(|item| { + item.map(|data| serde_json::to_value(data).unwrap_or(serde_json::Value::Null)) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, e)) + })) + } +} +``` + +## Testing Patterns + +### Integration Testing with Test Containers + +Comprehensive testing with real services: + +```rust +#[cfg(test)] +mod integration_tests { + use super::*; + use testcontainers::{clients, images, Container}; + use testcontainers::core::WaitFor; + + struct TestEnvironment { + _postgres_container: Container<'static, clients::Cli, images::postgres::Postgres>, + _redis_container: Container<'static, clients::Cli, images::redis::Redis>, + server: MyServer, + } + + impl TestEnvironment { + async fn new() -> Result> { + let docker = clients::Cli::default(); + + // Start PostgreSQL + let postgres_container = docker.run(images::postgres::Postgres::default()); + let postgres_port = postgres_container.get_host_port_ipv4(5432); + + // Start Redis + let redis_container = docker.run(images::redis::Redis::default()); + let redis_port = redis_container.get_host_port_ipv4(6379); + + // Configure server + let config = MyServerConfig { + database_url: format!("postgresql://postgres:postgres@localhost:{}/postgres", postgres_port), + redis_url: format!("redis://localhost:{}", redis_port), + ..Default::default() + }; + + let server = MyServer::with_config(config); + + // Run migrations + server.run_migrations().await?; + + Ok(Self { + _postgres_container: postgres_container, + _redis_container: redis_container, + server, + }) + } + } + + #[tokio::test] + async fn test_full_user_lifecycle() { + let env = TestEnvironment::new().await.unwrap(); + + // Create user + let create_request = CreateUserRequest { + name: "Integration Test User".to_string(), + email: "test@integration.com".to_string(), + initial_metadata: Some([("source".to_string(), "integration_test".to_string())].into_iter().collect()), + }; + + let user = env.server.create_user(create_request).await.unwrap(); + assert!(!user.id.is_empty()); + + // Verify user exists + let retrieved_user = env.server.get_user(user.id, Some(true)).await.unwrap(); + assert_eq!(retrieved_user.name, "Integration Test User"); + assert_eq!(retrieved_user.metadata.get("source"), Some(&"integration_test".to_string())); + + // Update user + let update_request = UpdateUserRequest { + name: Some("Updated User".to_string()), + active: Some(false), + ..Default::default() + }; + + let updated_user = env.server.update_user(user.id, update_request).await.unwrap(); + assert_eq!(updated_user.name, "Updated User"); + assert!(!updated_user.active); + + // Delete user + let deleted_user = env.server.delete_user(user.id).await.unwrap(); + assert_eq!(deleted_user.id, user.id); + + // Verify deletion + let not_found_result = env.server.get_user(user.id, None).await; + assert!(not_found_result.is_err()); + } +} +``` + +### Property-Based Testing + +Use property-based testing for robust validation: + +```rust +#[cfg(test)] +mod property_tests { + use super::*; + use proptest::prelude::*; + + proptest! { + #[test] + fn user_creation_idempotent(name in r"[a-zA-Z0-9 ]{1,50}", email in r"[a-z]+@[a-z]+\.[a-z]+") { + let rt = tokio::runtime::Runtime::new().unwrap(); + let server = MyServer::with_defaults(); + + rt.block_on(async { + let request1 = CreateUserRequest { + name: name.clone(), + email: email.clone(), + initial_metadata: None, + }; + + let request2 = CreateUserRequest { + name: name.clone(), + email: email.clone(), + initial_metadata: None, + }; + + // First creation should succeed + let result1 = server.create_user(request1).await; + prop_assert!(result1.is_ok()); + + // Second creation with same email should fail + let result2 = server.create_user(request2).await; + prop_assert!(result2.is_err()); + }); + } + } +} +``` + +--- + +These advanced patterns provide the foundation for building production-ready MCP servers with PulseEngine macros. Each pattern addresses specific architectural, security, performance, or testing concerns that arise in complex applications. \ No newline at end of file diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md new file mode 100644 index 00000000..0a388b08 --- /dev/null +++ b/docs/API_REFERENCE.md @@ -0,0 +1,539 @@ +# PulseEngine MCP Macros: API Reference + +Complete reference documentation for all PulseEngine MCP macro attributes, generated code, and APIs. + +## Server Macro: `#[mcp_server]` + +The `#[mcp_server]` macro transforms a Rust struct into a fully-featured MCP server. + +### Syntax + +```rust +#[mcp_server( + name = "Server Name", // Required: Display name + version = "1.0.0", // Optional: Version (defaults to Cargo.toml) + description = "Description", // Optional: Description (defaults to doc comments) + app_name = "app-id" // Optional: Application-specific storage isolation +)] +struct MyServer { + // Your server state +} +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | `String` | ✅ | Human-readable server name displayed to clients | +| `version` | `String` | ❌ | Server version (defaults to crate version) | +| `description` | `String` | ❌ | Server description (defaults to struct doc comments) | +| `app_name` | `String` | ❌ | Application identifier for storage isolation | + +### Generated Code + +The macro generates: + +- **Server Implementation**: Full MCP protocol compliance +- **Configuration Struct**: `{ServerName}Config` with server settings +- **Factory Methods**: `with_defaults()`, `with_config()`, `new()` +- **Transport Methods**: `serve_stdio()`, `serve_http()`, `serve_ws()` +- **Health Check**: Built-in health monitoring +- **Capability Detection**: Automatic feature discovery + +### Example + +```rust +use pulseengine_mcp_macros::mcp_server; + +#[mcp_server( + name = "File Manager Server", + version = "2.1.0", + description = "Advanced file management with security", + app_name = "filemanager" +)] +#[derive(Default, Clone)] +struct FileManagerServer { + root_path: std::path::PathBuf, + permissions: std::collections::HashMap>, +} +``` + +## Tool Macro: `#[mcp_tool]` + +The `#[mcp_tool]` macro exposes struct methods as MCP tools. + +### Syntax + +```rust +#[mcp_tool] +impl MyServer { + /// Tool description from doc comments + async fn tool_name(&self, param: Type) -> Result { + // Implementation + } +} +``` + +### Method Requirements + +- **Self Parameter**: Must take `&self` as first parameter +- **Async/Sync**: Both `async` and synchronous methods supported +- **Parameters**: All parameter types must implement `serde::Deserialize` +- **Return Types**: Must implement `serde::Serialize` or be `Result` where `T: Serialize` +- **Documentation**: Doc comments become tool descriptions + +### Supported Parameter Types + +| Type Category | Examples | Notes | +|---------------|----------|-------| +| **Primitives** | `i32`, `u64`, `f64`, `bool`, `String` | Direct JSON mapping | +| **Options** | `Option` | Optional parameters | +| **Collections** | `Vec`, `HashMap` | JSON arrays/objects | +| **Custom Types** | Structs with `#[derive(Deserialize)]` | Complex nested data | +| **Enums** | `#[derive(Deserialize)]` enums | Tagged or untagged variants | + +### Supported Return Types + +| Type Category | Examples | Notes | +|---------------|----------|-------| +| **Direct** | `String`, `i32`, `CustomStruct` | Serialized directly | +| **Results** | `Result` | Errors converted to MCP errors | +| **Options** | `Option` | `null` for `None` | +| **Collections** | `Vec`, `HashMap` | JSON arrays/objects | + +### Error Handling + +```rust +#[derive(Debug, thiserror::Error)] +enum MyError { + #[error("Not found: {id}")] + NotFound { id: u64 }, + #[error("Validation failed: {reason}")] + Validation { reason: String }, +} + +#[mcp_tool] +impl MyServer { + async fn risky_operation(&self, id: u64) -> Result { + // Errors automatically converted to MCP protocol errors + } +} +``` + +## Resource Macro: `#[mcp_resource]` + +The `#[mcp_resource]` macro creates MCP resources with URI template matching. + +### Syntax + +```rust +#[mcp_resource( + uri_template = "scheme://{param1}/{param2}", // Required: URI pattern + name = "resource_name", // Optional: Resource name + description = "Resource description", // Optional: Description + mime_type = "application/json" // Optional: Content type +)] +impl MyServer { + async fn resource_handler(&self, param1: String, param2: String) -> Result { + // Implementation + } +} +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `uri_template` | `String` | ✅ | URI pattern with `{param}` placeholders | +| `name` | `String` | ❌ | Resource identifier (defaults to method name) | +| `description` | `String` | ❌ | Resource description (defaults to doc comments) | +| `mime_type` | `String` | ❌ | Content MIME type (defaults to auto-detection) | + +### URI Template Syntax + +- **Parameters**: `{param_name}` extracts path segments +- **Schemes**: Any scheme supported (`file://`, `http://`, `custom://`) +- **Paths**: Static and dynamic path segments +- **Validation**: Automatic parameter extraction and validation + +### Examples + +```rust +#[mcp_resource(uri_template = "file://{path}")] +impl MyServer { + /// Read file contents + async fn read_file(&self, path: String) -> Result { + tokio::fs::read_to_string(&path).await + } +} + +#[mcp_resource( + uri_template = "api://{version}/{endpoint}/{id}", + mime_type = "application/json", + description = "REST API resource access" +)] +impl MyServer { + async fn api_resource(&self, version: String, endpoint: String, id: String) -> Result { + // API call implementation + } +} +``` + +## Prompt Macro: `#[mcp_prompt]` + +The `#[mcp_prompt]` macro creates prompt templates for AI interactions. + +### Syntax + +```rust +#[mcp_prompt( + name = "prompt_name", // Required: Prompt identifier + description = "Prompt description", // Optional: Description + arguments = ["arg1", "arg2"] // Optional: Argument names +)] +impl MyServer { + async fn prompt_handler(&self, arg1: String, arg2: String) -> Result { + // Implementation + } +} +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | `String` | ✅ | Prompt identifier for client requests | +| `description` | `String` | ❌ | Prompt description (defaults to doc comments) | +| `arguments` | `[String]` | ❌ | Expected argument names for validation | + +### Return Type + +Must return `Result` where: + +```rust +pub struct PromptMessage { + pub role: Role, + pub content: PromptContent, +} + +pub enum Role { + User, + Assistant, + System, +} + +pub enum PromptContent { + Text { text: String }, + Image { data: String, mime_type: String }, +} +``` + +### Examples + +```rust +use pulseengine_mcp_protocol::{PromptMessage, Role, PromptContent}; + +#[mcp_prompt(name = "code_review")] +impl MyServer { + /// Generate code review prompts + async fn code_review_prompt(&self, code: String, language: String) -> Result { + Ok(PromptMessage { + role: Role::User, + content: PromptContent::Text { + text: format!("Please review this {} code:\n\n```{}\n{}\n```", language, language, code), + }, + }) + } +} + +#[mcp_prompt( + name = "data_analysis", + description = "Generate data analysis prompts", + arguments = ["data", "analysis_type", "focus_areas"] +)] +impl MyServer { + async fn analysis_prompt(&self, data: serde_json::Value, analysis_type: String, focus_areas: Vec) -> Result { + let focus_text = focus_areas.join(", "); + let prompt_text = format!( + "Analyze this data with focus on {}:\n\nAnalysis type: {}\nData: {}\n\nProvide insights and recommendations.", + focus_text, analysis_type, serde_json::to_string_pretty(&data)? + ); + + Ok(PromptMessage { + role: Role::User, + content: PromptContent::Text { text: prompt_text }, + }) + } +} +``` + +## Generated Server API + +Every `#[mcp_server]` struct generates a comprehensive API: + +### Core Methods + +```rust +impl MyServer { + // Factory methods + fn with_defaults() -> Self; + fn with_config(config: MyServerConfig) -> Self; + fn new() -> Self; + + // Server information + fn get_server_info(&self) -> ServerInfo; + + // Transport methods + async fn serve_stdio(&self) -> Result; + async fn serve_http(&self, port: u16) -> Result; + async fn serve_ws(&self, addr: impl ToSocketAddrs) -> Result; + + // Health check + async fn health_check(&self) -> Result<(), Error>; +} +``` + +### MCP Backend Implementation + +```rust +impl McpBackend for MyServer { + // Tool operations + async fn list_tools(&self, params: ListToolsParams) -> Result; + async fn call_tool(&self, params: CallToolParams) -> Result; + + // Resource operations + async fn list_resources(&self, params: ListResourcesParams) -> Result; + async fn read_resource(&self, params: ReadResourceParams) -> Result; + + // Prompt operations + async fn list_prompts(&self, params: ListPromptsParams) -> Result; + async fn get_prompt(&self, params: GetPromptParams) -> Result; + + // Logging operations + async fn set_logging_level(&self, params: SetLoggingLevelParams) -> Result<(), Error>; +} +``` + +### Configuration Struct + +```rust +#[derive(Debug, Clone)] +pub struct MyServerConfig { + pub server_name: String, + pub server_version: String, + pub server_description: Option, + pub app_name: Option, + pub log_level: LogLevel, + pub max_request_size: usize, + pub timeout: Duration, + // Additional fields based on your server +} + +impl Default for MyServerConfig { + fn default() -> Self { + // Sensible defaults + } +} + +impl MyServerConfig { + pub fn builder() -> MyServerConfigBuilder; + + #[cfg(feature = "auth")] + pub fn get_auth_config() -> AuthConfig; +} +``` + +## Capability Detection + +The macro system automatically detects and enables MCP capabilities: + +### Automatic Detection + +- **Tools**: Enabled when `#[mcp_tool]` implementations found +- **Resources**: Enabled when `#[mcp_resource]` implementations found +- **Prompts**: Enabled when `#[mcp_prompt]` implementations found +- **Logging**: Always enabled with configurable levels + +### Manual Override + +```rust +impl MyServer { + fn override_capabilities(&self) -> Capabilities { + Capabilities { + tools: Some(ToolsCapability { list_changed: true }), + resources: Some(ResourcesCapability { subscribe: false, list_changed: true }), + prompts: Some(PromptsCapability { list_changed: true }), + logging: Some(LoggingCapability {}), + } + } +} +``` + +## Error Handling + +### Automatic Error Conversion + +All tool, resource, and prompt methods can return `Result` where `E` implements `std::error::Error`. Errors are automatically converted to appropriate MCP protocol errors. + +### Custom Error Types + +```rust +#[derive(Debug, thiserror::Error)] +pub enum MyServerError { + #[error("Resource not found: {resource}")] + NotFound { resource: String }, + + #[error("Access denied: {reason}")] + AccessDenied { reason: String }, + + #[error("Invalid input: {field}")] + InvalidInput { field: String }, + + #[error("Internal error: {source}")] + Internal { #[from] source: Box }, +} +``` + +### Error Mapping + +| Rust Error Kind | MCP Error Code | Description | +|------------------|----------------|-------------| +| `InvalidInput` | `-32602` | Invalid parameters | +| `NotFound` | `-32001` | Resource/method not found | +| `PermissionDenied` | `-32003` | Access denied | +| `Other` | `-32000` | Internal error | + +## Type System Integration + +### Serialization Requirements + +- **Parameters**: Must implement `serde::Deserialize` +- **Return Values**: Must implement `serde::Serialize` +- **Error Types**: Must implement `std::error::Error + Send + Sync` + +### Complex Types + +```rust +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct User { + pub id: u64, + pub name: String, + pub email: String, + pub metadata: std::collections::HashMap, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct PaginationParams { + pub limit: Option, + pub offset: Option, + pub sort_by: Option, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct PaginatedResponse { + pub items: Vec, + pub total: u64, + pub has_more: bool, +} +``` + +## Application-Specific Configuration + +When using `app_name`, the server creates isolated storage and configuration: + +### Storage Isolation + +- **Config Path**: `~/.pulseengine/{app_name}/config/` +- **Data Path**: `~/.pulseengine/{app_name}/data/` +- **Cache Path**: `~/.pulseengine/{app_name}/cache/` +- **Logs Path**: `~/.pulseengine/{app_name}/logs/` + +### Authentication Integration + +```rust +#[cfg(feature = "auth")] +impl MyServer { + fn get_auth_manager(&self) -> &AuthManager { + // App-specific auth manager + } + + fn verify_api_key(&self, key: &str) -> Result { + // App-specific key validation + } +} +``` + +## Threading and Concurrency + +All generated servers are: + +- **Clone**: Can be safely cloned and shared +- **Send + Sync**: Can be used across thread boundaries +- **Thread-Safe**: Internal state properly synchronized + +### Concurrent Access Patterns + +```rust +use std::sync::Arc; +use tokio::sync::RwLock; + +#[mcp_server(name = "Concurrent Server")] +#[derive(Clone)] +struct ConcurrentServer { + shared_state: Arc>>, +} + +#[mcp_tool] +impl ConcurrentServer { + async fn concurrent_operation(&self, key: String) -> Result { + let state = self.shared_state.read().await; + Ok(state.get(&key).cloned().unwrap_or_default()) + } +} +``` + +## Performance Considerations + +### Memory Usage + +- **Zero-Copy**: URI template parsing avoids unnecessary allocations +- **Efficient Serialization**: Direct serde integration +- **Lazy Initialization**: Resources loaded on-demand + +### Async Performance + +- **Tokio Integration**: Full async/await support +- **Connection Pooling**: Automatic for HTTP/WebSocket transports +- **Backpressure**: Built-in flow control + +### Benchmarking + +```rust +#[cfg(test)] +mod benchmarks { + use super::*; + use criterion::{black_box, criterion_group, criterion_main, Criterion}; + + fn benchmark_tool_call(c: &mut Criterion) { + let server = MyServer::with_defaults(); + let rt = tokio::runtime::Runtime::new().unwrap(); + + c.bench_function("tool_call", |b| { + b.iter(|| { + rt.block_on(async { + black_box(server.my_tool("test".to_string()).await) + }) + }) + }); + } + + criterion_group!(benches, benchmark_tool_call); + criterion_main!(benches); +} +``` + +--- + +This API reference provides complete documentation for all macro features and generated code. For practical examples and patterns, see the [Macro Guide](./MACRO_GUIDE.md) and [Advanced Patterns](./ADVANCED_PATTERNS.md). \ No newline at end of file diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 00000000..1e91be04 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,995 @@ +# PulseEngine MCP Macros: Deployment Guide + +This guide covers production deployment strategies for MCP servers built with PulseEngine macros. + +## Deployment Architectures + +### Standalone Deployment + +Deploy as a single binary with embedded transport: + +```rust +use pulseengine_mcp_macros::mcp_server; +use clap::{Arg, Command}; +use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt}; + +#[mcp_server( + name = "Production Server", + app_name = "myapp", + version = "1.0.0" +)] +#[derive(Clone)] +pub struct ProductionServer { + config: Arc, +} + +#[tokio::main] +async fn main() -> Result<(), Box> { + // Parse command line arguments + let matches = Command::new("myapp-mcp-server") + .version("1.0.0") + .arg(Arg::new("transport") + .long("transport") + .value_name("TRANSPORT") + .help("Transport type: stdio, http, websocket") + .default_value("stdio")) + .arg(Arg::new("port") + .long("port") + .value_name("PORT") + .help("Port for HTTP/WebSocket transport") + .default_value("8080")) + .arg(Arg::new("config") + .long("config") + .value_name("FILE") + .help("Configuration file path")) + .get_matches(); + + // Initialize logging + tracing_subscriber::registry() + .with(tracing_subscriber::EnvFilter::new( + std::env::var("RUST_LOG").unwrap_or_else(|_| "myapp=info,pulseengine_mcp=info".into()) + )) + .with(tracing_subscriber::fmt::layer()) + .init(); + + // Load configuration + let config = if let Some(config_path) = matches.get_one::("config") { + ServerConfig::from_file(config_path).await? + } else { + ServerConfig::from_env()? + }; + + // Create server + let server = ProductionServer::with_config(config); + + // Setup graceful shutdown + let shutdown_signal = async { + tokio::signal::ctrl_c().await.expect("Failed to listen for Ctrl+C"); + tracing::info!("Shutdown signal received"); + }; + + // Start server based on transport + let transport = matches.get_one::("transport").unwrap(); + let service = match transport.as_str() { + "stdio" => { + tracing::info!("Starting MCP server with STDIO transport"); + server.serve_stdio().await? + } + "http" => { + let port: u16 = matches.get_one::("port").unwrap().parse()?; + tracing::info!("Starting MCP server with HTTP transport on port {}", port); + server.serve_http(port).await? + } + "websocket" => { + let port: u16 = matches.get_one::("port").unwrap().parse()?; + let addr = format!("0.0.0.0:{}", port); + tracing::info!("Starting MCP server with WebSocket transport on {}", addr); + server.serve_ws(&addr).await? + } + _ => return Err(format!("Unknown transport: {}", transport).into()), + }; + + // Run with graceful shutdown + service.run_with_shutdown(shutdown_signal).await?; + + tracing::info!("Server shutdown complete"); + Ok(()) +} +``` + +### Containerized Deployment + +Deploy using Docker containers: + +```dockerfile +# Dockerfile +FROM rust:1.88-slim as builder + +WORKDIR /app +COPY . . + +# Build dependencies first for better caching +RUN --mount=type=cache,target=/usr/local/cargo/registry \ + --mount=type=cache,target=/app/target \ + cargo build --release + +# Runtime image +FROM debian:bookworm-slim + +# Install runtime dependencies +RUN apt-get update && apt-get install -y \ + ca-certificates \ + libssl3 \ + && rm -rf /var/lib/apt/lists/* + +# Create app user +RUN useradd -r -s /bin/false appuser + +# Copy binary +COPY --from=builder /app/target/release/myapp-mcp-server /usr/local/bin/ + +# Create directories for app-specific storage +RUN mkdir -p /app/data /app/config /app/logs && \ + chown -R appuser:appuser /app + +USER appuser +WORKDIR /app + +# Health check +HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ + CMD /usr/local/bin/myapp-mcp-server --transport http --port 8080 || exit 1 + +EXPOSE 8080 +CMD ["/usr/local/bin/myapp-mcp-server", "--transport", "http", "--port", "8080"] +``` + +```yaml +# docker-compose.yml +version: '3.8' +services: + mcp-server: + build: . + ports: + - "8080:8080" + environment: + - RUST_LOG=info + - DATABASE_URL=postgresql://postgres:password@db:5432/myapp + - REDIS_URL=redis://redis:6379 + volumes: + - ./config:/app/config:ro + - ./data:/app/data + - ./logs:/app/logs + depends_on: + - db + - redis + restart: unless-stopped + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/health"] + interval: 30s + timeout: 10s + retries: 3 + + db: + image: postgres:15-alpine + environment: + - POSTGRES_DB=myapp + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=password + volumes: + - postgres_data:/var/lib/postgresql/data + restart: unless-stopped + + redis: + image: redis:7-alpine + volumes: + - redis_data:/data + restart: unless-stopped + +volumes: + postgres_data: + redis_data: +``` + +### Kubernetes Deployment + +Deploy on Kubernetes with high availability: + +```yaml +# k8s/namespace.yaml +apiVersion: v1 +kind: Namespace +metadata: + name: mcp-system +--- +# k8s/configmap.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: mcp-server-config + namespace: mcp-system +data: + config.toml: | + [server] + name = "Production MCP Server" + version = "1.0.0" + max_connections = 1000 + + [database] + url = "postgresql://postgres:password@postgres:5432/myapp" + max_connections = 20 + + [redis] + url = "redis://redis:6379" + max_connections = 10 + + [logging] + level = "info" + format = "json" +--- +# k8s/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: mcp-server + namespace: mcp-system +spec: + replicas: 3 + selector: + matchLabels: + app: mcp-server + template: + metadata: + labels: + app: mcp-server + spec: + containers: + - name: mcp-server + image: myapp/mcp-server:1.0.0 + ports: + - containerPort: 8080 + env: + - name: RUST_LOG + value: "info" + - name: CONFIG_PATH + value: "/etc/config/config.toml" + volumeMounts: + - name: config + mountPath: /etc/config + readOnly: true + - name: data + mountPath: /app/data + resources: + requests: + memory: "128Mi" + cpu: "100m" + limits: + memory: "512Mi" + cpu: "500m" + livenessProbe: + httpGet: + path: /health + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 5 + volumes: + - name: config + configMap: + name: mcp-server-config + - name: data + persistentVolumeClaim: + claimName: mcp-server-data +--- +# k8s/service.yaml +apiVersion: v1 +kind: Service +metadata: + name: mcp-server + namespace: mcp-system +spec: + selector: + app: mcp-server + ports: + - protocol: TCP + port: 80 + targetPort: 8080 + type: ClusterIP +--- +# k8s/ingress.yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: mcp-server + namespace: mcp-system + annotations: + nginx.ingress.kubernetes.io/rewrite-target: / + cert-manager.io/cluster-issuer: letsencrypt-prod +spec: + tls: + - hosts: + - mcp.example.com + secretName: mcp-server-tls + rules: + - host: mcp.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: mcp-server + port: + number: 80 +``` + +## Configuration Management + +### Configuration Structure + +```toml +# config/production.toml +[server] +name = "Production MCP Server" +version = "1.0.0" +description = "Production deployment of MyApp MCP server" +app_name = "myapp" +bind_address = "0.0.0.0:8080" +max_connections = 1000 +request_timeout = 30 +shutdown_timeout = 10 + +[database] +url = "postgresql://user:pass@localhost:5432/myapp" +max_connections = 20 +min_connections = 5 +connection_timeout = 30 +idle_timeout = 600 + +[redis] +url = "redis://localhost:6379" +max_connections = 10 +connection_timeout = 5 + +[auth] +enabled = true +api_key_header = "X-API-Key" +jwt_secret = "${JWT_SECRET}" +token_expiry = 3600 + +[logging] +level = "info" +format = "json" +file_path = "/app/logs/server.log" +max_file_size = "100MB" +max_files = 10 + +[metrics] +enabled = true +prometheus_endpoint = "/metrics" +namespace = "myapp_mcp" + +[security] +cors_enabled = true +cors_origins = ["https://app.example.com"] +rate_limit = 100 +rate_limit_window = 60 + +[features] +cache_enabled = true +batch_processing = true +streaming = true +``` + +### Environment-Based Configuration + +```rust +use config::{Config, ConfigError, Environment, File}; +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ServerConfig { + pub server: ServerSettings, + pub database: DatabaseSettings, + pub redis: RedisSettings, + pub auth: AuthSettings, + pub logging: LoggingSettings, + pub metrics: MetricsSettings, + pub security: SecuritySettings, + pub features: FeatureFlags, +} + +impl ServerConfig { + pub fn from_env() -> Result { + let env = std::env::var("ENVIRONMENT").unwrap_or_else(|_| "development".into()); + + let config = Config::builder() + // Default configuration + .add_source(File::with_name("config/default")) + // Environment-specific configuration + .add_source(File::with_name(&format!("config/{}", env)).required(false)) + // Local overrides + .add_source(File::with_name("config/local").required(false)) + // Environment variables + .add_source(Environment::with_prefix("MYAPP").separator("_")) + .build()?; + + config.try_deserialize() + } + + pub async fn from_file>(path: P) -> Result { + let config = Config::builder() + .add_source(File::from(path.as_ref())) + .add_source(Environment::with_prefix("MYAPP").separator("_")) + .build()?; + + config.try_deserialize() + } + + pub fn validate(&self) -> Result<(), ConfigError> { + // Validate database URL + if self.database.url.is_empty() { + return Err(ConfigError::Message("Database URL is required".into())); + } + + // Validate connection limits + if self.database.max_connections == 0 { + return Err(ConfigError::Message("Database max_connections must be > 0".into())); + } + + // Validate auth settings if enabled + if self.auth.enabled && self.auth.jwt_secret.is_empty() { + return Err(ConfigError::Message("JWT secret is required when auth is enabled".into())); + } + + Ok(()) + } +} +``` + +## Monitoring and Observability + +### Metrics Collection + +```rust +use prometheus::{Counter, Histogram, IntGauge, Registry}; +use std::sync::Arc; + +#[derive(Clone)] +pub struct Metrics { + registry: Arc, + request_count: Counter, + request_duration: Histogram, + active_connections: IntGauge, + tool_calls: Counter, + resource_reads: Counter, + prompt_generations: Counter, + errors: Counter, +} + +impl Metrics { + pub fn new(namespace: &str) -> Result { + let registry = Arc::new(Registry::new()); + + let request_count = Counter::new( + format!("{}_requests_total", namespace), + "Total number of requests processed" + )?; + + let request_duration = Histogram::with_opts( + prometheus::HistogramOpts::new( + format!("{}_request_duration_seconds", namespace), + "Request duration in seconds" + ).buckets(vec![0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 2.5, 5.0, 10.0]) + )?; + + let active_connections = IntGauge::new( + format!("{}_active_connections", namespace), + "Number of active connections" + )?; + + let tool_calls = Counter::new( + format!("{}_tool_calls_total", namespace), + "Total number of tool calls" + )?; + + let resource_reads = Counter::new( + format!("{}_resource_reads_total", namespace), + "Total number of resource reads" + )?; + + let prompt_generations = Counter::new( + format!("{}_prompt_generations_total", namespace), + "Total number of prompt generations" + )?; + + let errors = Counter::new( + format!("{}_errors_total", namespace), + "Total number of errors" + )?; + + // Register metrics + registry.register(Box::new(request_count.clone()))?; + registry.register(Box::new(request_duration.clone()))?; + registry.register(Box::new(active_connections.clone()))?; + registry.register(Box::new(tool_calls.clone()))?; + registry.register(Box::new(resource_reads.clone()))?; + registry.register(Box::new(prompt_generations.clone()))?; + registry.register(Box::new(errors.clone()))?; + + Ok(Self { + registry, + request_count, + request_duration, + active_connections, + tool_calls, + resource_reads, + prompt_generations, + errors, + }) + } + + pub fn record_request(&self, duration: f64) { + self.request_count.inc(); + self.request_duration.observe(duration); + } + + pub fn increment_active_connections(&self) { + self.active_connections.inc(); + } + + pub fn decrement_active_connections(&self) { + self.active_connections.dec(); + } + + pub fn record_tool_call(&self) { + self.tool_calls.inc(); + } + + pub fn record_resource_read(&self) { + self.resource_reads.inc(); + } + + pub fn record_prompt_generation(&self) { + self.prompt_generations.inc(); + } + + pub fn record_error(&self) { + self.errors.inc(); + } + + pub fn registry(&self) -> Arc { + self.registry.clone() + } +} + +// Integrate metrics into server +#[mcp_server(name = "Monitored Server")] +#[derive(Clone)] +pub struct MonitoredServer { + metrics: Metrics, + inner: Arc>, +} + +impl MonitoredServer { + pub async fn serve_with_metrics(&self, port: u16) -> Result<(), ServerError> { + let metrics = self.metrics.clone(); + + // Start metrics endpoint + let metrics_handler = { + let registry = metrics.registry(); + move || { + let encoder = prometheus::TextEncoder::new(); + let metric_families = registry.gather(); + encoder.encode_to_string(&metric_families).unwrap_or_default() + } + }; + + // Serve metrics on /metrics endpoint + let metrics_route = warp::path("metrics") + .and(warp::get()) + .map(metrics_handler); + + // Serve main MCP endpoints with metrics middleware + let mcp_routes = self.create_mcp_routes() + .with(warp::filters::trace::trace(|info| { + let start = std::time::Instant::now(); + tracing::info_span!("request", method = %info.method(), path = %info.path()) + })) + .with(warp::wrap_fn(move |req, next| { + let metrics = metrics.clone(); + async move { + metrics.increment_active_connections(); + let start = std::time::Instant::now(); + + let result = next.run(req).await; + + let duration = start.elapsed().as_secs_f64(); + metrics.record_request(duration); + metrics.decrement_active_connections(); + + result + } + })); + + let routes = metrics_route.or(mcp_routes); + + warp::serve(routes) + .run(([0, 0, 0, 0], port)) + .await; + + Ok(()) + } +} +``` + +### Distributed Tracing + +```rust +use opentelemetry::{ + trace::{TraceContextExt, Tracer}, + Context, KeyValue, +}; +use opentelemetry_jaeger::new_agent_pipeline; +use tracing_opentelemetry::OpenTelemetryLayer; +use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt}; + +pub async fn init_tracing(service_name: &str) -> Result<(), Box> { + // Initialize Jaeger tracer + let tracer = new_agent_pipeline() + .with_service_name(service_name) + .with_auto_split_batch(true) + .install_batch(opentelemetry::runtime::Tokio)?; + + // Initialize tracing subscriber with OpenTelemetry layer + tracing_subscriber::registry() + .with(tracing_subscriber::EnvFilter::new( + std::env::var("RUST_LOG").unwrap_or_else(|_| "info".into()) + )) + .with(tracing_subscriber::fmt::layer()) + .with(OpenTelemetryLayer::new(tracer)) + .try_init()?; + + Ok(()) +} + +#[mcp_tool] +impl MonitoredServer { + /// Tool with distributed tracing + #[tracing::instrument(skip(self), fields(tool_name = "traced_operation"))] + async fn traced_operation(&self, input: String) -> Result { + let span = tracing::Span::current(); + span.record("input_length", input.len()); + + // Child span for database operation + let db_result = { + let _db_span = tracing::info_span!("database_query").entered(); + self.query_database(&input).await? + }; + + // Child span for processing + let processed = { + let _process_span = tracing::info_span!("data_processing").entered(); + self.process_data(db_result).await? + }; + + span.record("output_length", processed.len()); + Ok(processed) + } +} +``` + +## Security Hardening + +### TLS Configuration + +```rust +use rustls::{Certificate, PrivateKey, ServerConfig as TlsConfig}; +use std::io::BufReader; + +pub struct TlsManager { + config: Arc, +} + +impl TlsManager { + pub fn new(cert_path: &str, key_path: &str) -> Result { + // Load certificates + let cert_file = std::fs::File::open(cert_path)?; + let mut cert_reader = BufReader::new(cert_file); + let certs = rustls_pemfile::certs(&mut cert_reader)? + .into_iter() + .map(Certificate) + .collect(); + + // Load private key + let key_file = std::fs::File::open(key_path)?; + let mut key_reader = BufReader::new(key_file); + let keys = rustls_pemfile::pkcs8_private_keys(&mut key_reader)?; + + if keys.is_empty() { + return Err(TlsError::NoPrivateKey); + } + + let key = PrivateKey(keys[0].clone()); + + // Configure TLS + let config = TlsConfig::builder() + .with_safe_default_cipher_suites() + .with_safe_default_kx_groups() + .with_safe_default_protocol_versions()? + .with_no_client_auth() + .with_single_cert(certs, key)?; + + Ok(Self { + config: Arc::new(config), + }) + } + + pub fn config(&self) -> Arc { + self.config.clone() + } +} + +// Use TLS in server +impl ProductionServer { + pub async fn serve_https(&self, port: u16, tls_manager: TlsManager) -> Result { + use warp::Filter; + + let routes = self.create_routes(); + + warp::serve(routes) + .tls() + .cert_path("path/to/cert.pem") + .key_path("path/to/key.pem") + .run(([0, 0, 0, 0], port)) + .await; + + Ok(()) + } +} +``` + +### Rate Limiting and DDoS Protection + +```rust +use governor::{Quota, RateLimiter}; +use std::net::IpAddr; +use std::collections::HashMap; + +#[derive(Clone)] +pub struct RateLimitManager { + global_limiter: Arc>, + per_ip_limiters: Arc>>>>, + quota: Quota, +} + +impl RateLimitManager { + pub fn new(requests_per_minute: u32, burst_size: u32) -> Self { + let quota = Quota::per_minute(nonzero::NonZeroU32::new(requests_per_minute).unwrap()) + .allow_burst(nonzero::NonZeroU32::new(burst_size).unwrap()); + + let global_limiter = Arc::new(RateLimiter::direct(quota)); + + Self { + global_limiter, + per_ip_limiters: Arc::new(RwLock::new(HashMap::new())), + quota, + } + } + + pub async fn check_rate_limit(&self, ip: IpAddr) -> Result<(), RateLimitError> { + // Check global rate limit + self.global_limiter.check().map_err(|_| RateLimitError::GlobalLimitExceeded)?; + + // Check per-IP rate limit + let limiters = self.per_ip_limiters.read().await; + let limiter = if let Some(limiter) = limiters.get(&ip) { + limiter.clone() + } else { + drop(limiters); + let mut limiters = self.per_ip_limiters.write().await; + let limiter = Arc::new(RateLimiter::direct(self.quota)); + limiters.insert(ip, limiter.clone()); + limiter + }; + + limiter.check().map_err(|_| RateLimitError::IpLimitExceeded { ip }) + } +} + +// Integrate rate limiting +impl ProductionServer { + pub async fn serve_with_rate_limiting(&self, port: u16) -> Result<(), ServerError> { + let rate_limiter = RateLimitManager::new(100, 10); // 100 requests per minute, burst of 10 + + let routes = self.create_routes() + .with(warp::wrap_fn(move |req, next| { + let rate_limiter = rate_limiter.clone(); + async move { + let ip = req.remote_addr() + .map(|addr| addr.ip()) + .unwrap_or(IpAddr::V4(std::net::Ipv4Addr::LOCALHOST)); + + if let Err(e) = rate_limiter.check_rate_limit(ip).await { + return Ok(warp::reply::with_status( + warp::reply::json(&serde_json::json!({ + "error": "Rate limit exceeded", + "details": e.to_string() + })), + warp::http::StatusCode::TOO_MANY_REQUESTS + ).into_response()); + } + + next.run(req).await + } + })); + + warp::serve(routes).run(([0, 0, 0, 0], port)).await; + Ok(()) + } +} +``` + +## High Availability and Load Balancing + +### Health Checks + +```rust +#[derive(Debug, Serialize, Deserialize)] +pub struct HealthStatus { + pub status: String, + pub timestamp: DateTime, + pub version: String, + pub uptime: Duration, + pub checks: HashMap, +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct ComponentHealth { + pub status: String, + pub response_time_ms: u64, + pub details: Option, +} + +impl ProductionServer { + pub async fn health_check(&self) -> HealthStatus { + let start_time = self.start_time; + let uptime = Utc::now().signed_duration_since(start_time); + + let mut checks = HashMap::new(); + + // Database health check + let db_start = std::time::Instant::now(); + let db_health = match self.check_database_health().await { + Ok(_) => ComponentHealth { + status: "healthy".to_string(), + response_time_ms: db_start.elapsed().as_millis() as u64, + details: None, + }, + Err(e) => ComponentHealth { + status: "unhealthy".to_string(), + response_time_ms: db_start.elapsed().as_millis() as u64, + details: Some(e.to_string()), + }, + }; + checks.insert("database".to_string(), db_health); + + // Redis health check + let redis_start = std::time::Instant::now(); + let redis_health = match self.check_redis_health().await { + Ok(_) => ComponentHealth { + status: "healthy".to_string(), + response_time_ms: redis_start.elapsed().as_millis() as u64, + details: None, + }, + Err(e) => ComponentHealth { + status: "unhealthy".to_string(), + response_time_ms: redis_start.elapsed().as_millis() as u64, + details: Some(e.to_string()), + }, + }; + checks.insert("redis".to_string(), redis_health); + + // Overall status + let overall_status = if checks.values().all(|h| h.status == "healthy") { + "healthy" + } else { + "unhealthy" + }; + + HealthStatus { + status: overall_status.to_string(), + timestamp: Utc::now(), + version: env!("CARGO_PKG_VERSION").to_string(), + uptime: uptime.to_std().unwrap_or_default(), + checks, + } + } + + async fn check_database_health(&self) -> Result<(), DatabaseError> { + // Simple query to check database connectivity + let _result = self.database_pool.get().await? + .query_one("SELECT 1", &[]).await?; + Ok(()) + } + + async fn check_redis_health(&self) -> Result<(), RedisError> { + let mut conn = self.redis_pool.get().await?; + let _result: String = redis::cmd("PING").query_async(&mut *conn).await?; + Ok(()) + } +} +``` + +### Load Balancer Configuration + +```nginx +# nginx.conf +upstream mcp_servers { + least_conn; + server mcp-server-1:8080 max_fails=3 fail_timeout=30s; + server mcp-server-2:8080 max_fails=3 fail_timeout=30s; + server mcp-server-3:8080 max_fails=3 fail_timeout=30s; +} + +server { + listen 80; + listen 443 ssl http2; + server_name mcp.example.com; + + ssl_certificate /etc/ssl/certs/mcp.example.com.crt; + ssl_certificate_key /etc/ssl/private/mcp.example.com.key; + + # Security headers + add_header X-Frame-Options DENY; + add_header X-Content-Type-Options nosniff; + add_header X-XSS-Protection "1; mode=block"; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + + # Rate limiting + limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s; + limit_req zone=api burst=20 nodelay; + + location /health { + proxy_pass http://mcp_servers/health; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # Health check specific settings + proxy_connect_timeout 5s; + proxy_send_timeout 5s; + proxy_read_timeout 5s; + } + + location / { + proxy_pass http://mcp_servers; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocket support + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Timeouts + proxy_connect_timeout 10s; + proxy_send_timeout 60s; + proxy_read_timeout 60s; + + # Buffer settings + proxy_buffering on; + proxy_buffer_size 4k; + proxy_buffers 8 4k; + } +} +``` + +This deployment guide provides comprehensive strategies for production deployment of MCP servers built with PulseEngine macros, covering containerization, orchestration, monitoring, security, and high availability patterns. \ No newline at end of file diff --git a/docs/MACRO_GUIDE.md b/docs/MACRO_GUIDE.md new file mode 100644 index 00000000..8fafb697 --- /dev/null +++ b/docs/MACRO_GUIDE.md @@ -0,0 +1,470 @@ +# PulseEngine MCP Macros: Complete Guide + +A comprehensive guide to building Model Context Protocol servers using PulseEngine's powerful macro system. + +## Overview + +PulseEngine MCP Macros dramatically simplify building MCP servers by automatically generating protocol-compliant code from simple Rust function annotations. This guide follows the patterns from the [official MCP tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms) while leveraging the power of Rust macros. + +## Quick Start + +### 1. Preparing Your Project + +Add PulseEngine MCP Macros to your `Cargo.toml`: + +```toml +[dependencies] +pulseengine-mcp-macros = "0.6" +tokio = { version = "1.0", features = ["full"] } +serde = { version = "1.0", features = ["derive"] } +``` + +### 2. Building Your First Server + +Create a simple MCP server with just a few lines: + +```rust +use pulseengine_mcp_macros::mcp_server; + +#[mcp_server(name = "My First Server")] +#[derive(Default, Clone)] +struct MyServer; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let server = MyServer::with_defaults(); + server.serve_stdio().await?.run().await?; + Ok(()) +} +``` + +That's it! You now have a working MCP server that Claude can connect to. + +## Core Concepts + +### Server Declaration + +The `#[mcp_server]` macro transforms a simple struct into a fully-featured MCP server: + +```rust +#[mcp_server( + name = "Advanced Server", + version = "1.0.0", + description = "A sophisticated MCP server", + app_name = "my-app" // For isolated storage +)] +#[derive(Default, Clone)] +struct AdvancedServer { + // Your server state here +} +``` + +**Key Parameters:** +- `name` - Display name for your server (required) +- `version` - Server version (defaults to Cargo.toml version) +- `description` - Server description (defaults to doc comments) +- `app_name` - Application name for storage isolation (optional) + +### Adding Tools + +Tools are the core functionality of your MCP server. Use `#[mcp_tool]` to expose functions: + +```rust +use pulseengine_mcp_macros::mcp_tool; + +#[mcp_tool] +impl AdvancedServer { + /// Calculate the sum of two numbers + async fn add(&self, a: f64, b: f64) -> f64 { + a + b + } + + /// Process text with various operations + async fn process_text(&self, text: String, operation: String) -> Result { + match operation.as_str() { + "uppercase" => Ok(text.to_uppercase()), + "reverse" => Ok(text.chars().rev().collect()), + _ => Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Unknown operation" + )) + } + } +} +``` + +**Tool Features:** +- **Automatic Schema Generation** - Parameter types become JSON schemas +- **Error Handling** - Rust errors are converted to MCP protocol errors +- **Documentation** - Doc comments become tool descriptions +- **Type Safety** - Compile-time validation of parameters + +### Adding Resources + +Resources provide access to external data. Use `#[mcp_resource]` with URI templates: + +```rust +use pulseengine_mcp_macros::mcp_resource; + +#[mcp_resource(uri_template = "file://{path}")] +impl AdvancedServer { + /// Read a file from the filesystem + async fn read_file(&self, path: String) -> Result { + tokio::fs::read_to_string(&path).await + } +} + +#[mcp_resource( + uri_template = "api://{endpoint}/{id}", + mime_type = "application/json" +)] +impl AdvancedServer { + /// Fetch data from an API endpoint + async fn api_data(&self, endpoint: String, id: String) -> Result { + // Your API call logic here + Ok(serde_json::json!({ + "endpoint": endpoint, + "id": id, + "data": "example" + })) + } +} +``` + +**Resource Features:** +- **URI Templates** - Flexible parameter extraction from URIs +- **MIME Type Support** - Specify content types for proper handling +- **Path Parameters** - Automatic extraction and validation +- **Content Negotiation** - Support for various content types + +### Adding Prompts + +Prompts help Claude generate better responses. Use `#[mcp_prompt]`: + +```rust +use pulseengine_mcp_macros::mcp_prompt; +use pulseengine_mcp_protocol::{PromptMessage, Role, PromptContent}; + +#[mcp_prompt(name = "code_review")] +impl AdvancedServer { + /// Generate a code review prompt + async fn code_review_prompt(&self, code: String, language: String) -> Result { + Ok(PromptMessage { + role: Role::User, + content: PromptContent::Text { + text: format!( + "Please review this {} code and provide feedback:\n\n```{}\n{}\n```", + language, language, code + ), + }, + }) + } +} +``` + +## Advanced Patterns + +### Application-Specific Configuration + +Use `app_name` to isolate storage and configuration: + +```rust +#[mcp_server( + name = "MyApp Server", + app_name = "myapp" // Creates isolated ~/.pulseengine/myapp/ directory +)] +#[derive(Default, Clone)] +struct MyAppServer; +``` + +This prevents conflicts when running multiple MCP servers on the same system. + +### Complex Data Types + +The macro system supports sophisticated data structures: + +```rust +use serde::{Deserialize, Serialize}; + +#[derive(Serialize, Deserialize)] +struct User { + id: u64, + name: String, + email: String, +} + +#[mcp_tool] +impl AdvancedServer { + /// Create a new user + async fn create_user(&self, user_data: User) -> Result { + // Validation and processing + Ok(user_data) + } + + /// Search users with complex parameters + async fn search_users(&self, + query: Option, + limit: Option, + filters: std::collections::HashMap + ) -> Vec { + // Your search logic here + vec![] + } +} +``` + +### Error Handling Best Practices + +Design robust error handling for production use: + +```rust +#[derive(Debug, thiserror::Error)] +enum MyServerError { + #[error("User not found: {id}")] + UserNotFound { id: u64 }, + #[error("Invalid input: {message}")] + InvalidInput { message: String }, + #[error("Database error: {0}")] + Database(#[from] sqlx::Error), +} + +#[mcp_tool] +impl AdvancedServer { + /// Example with proper error handling + async fn get_user(&self, id: u64) -> Result { + // Your logic here + Err(MyServerError::UserNotFound { id }) + } +} +``` + +### Performance and Concurrency + +Design for high-performance concurrent access: + +```rust +use std::sync::Arc; +use tokio::sync::RwLock; + +#[mcp_server(name = "High Performance Server")] +#[derive(Clone)] +struct PerformanceServer { + data: Arc>>, +} + +impl Default for PerformanceServer { + fn default() -> Self { + Self { + data: Arc::new(RwLock::new(std::collections::HashMap::new())), + } + } +} + +#[mcp_tool] +impl PerformanceServer { + /// Concurrent-safe data access + async fn get_data(&self, key: String) -> Option { + let data = self.data.read().await; + data.get(&key).cloned() + } + + /// Batch processing for efficiency + async fn process_batch(&self, items: Vec) -> Vec { + // Process items concurrently + let tasks: Vec<_> = items.into_iter() + .map(|item| async move { format!("processed: {}", item) }) + .collect(); + + futures::future::join_all(tasks).await + } +} +``` + +## Working with Claude + +### Optimal Tool Design + +When designing tools for Claude, follow these principles: + +- **Clear Naming** - Use descriptive function names that explain the purpose +- **Rich Documentation** - Write comprehensive doc comments +- **Logical Parameters** - Group related parameters together +- **Consistent Returns** - Use consistent return types across similar tools + +```rust +#[mcp_tool] +impl AdvancedServer { + /// Analyze text sentiment and extract key insights + /// + /// This tool processes natural language text to determine emotional tone + /// and extract meaningful insights for content analysis. + /// + /// # Parameters + /// - `text`: The text content to analyze + /// - `detailed`: Whether to include detailed breakdown + /// + /// # Returns + /// A structured analysis with sentiment scores and key insights + async fn analyze_sentiment(&self, + text: String, + detailed: Option + ) -> Result { + // Your analysis logic + todo!() + } +} +``` + +### Resource Organization + +Structure resources to match Claude's mental model: + +```rust +// Hierarchical data access +#[mcp_resource(uri_template = "docs://{category}/{document}")] +impl AdvancedServer { + async fn documentation(&self, category: String, document: String) -> Result { + // Return documentation content + } +} + +// Dynamic content generation +#[mcp_resource(uri_template = "reports://{type}/{date_range}")] +impl AdvancedServer { + async fn generate_report(&self, report_type: String, date_range: String) -> Result { + // Generate and return report + } +} +``` + +### Prompt Engineering + +Create prompts that help Claude understand your domain: + +```rust +#[mcp_prompt(name = "database_query")] +impl AdvancedServer { + /// Generate optimized database queries + async fn database_query_prompt(&self, + table_schema: String, + requirements: String + ) -> Result { + let prompt_text = format!( + "Given this database schema:\n\n{}\n\nGenerate an optimized SQL query that: {}\n\nConsider:\n- Performance implications\n- Index usage\n- Security (prevent SQL injection)\n- Readability and maintainability", + table_schema, + requirements + ); + + Ok(PromptMessage { + role: Role::User, + content: PromptContent::Text { text: prompt_text }, + }) + } +} +``` + +## Best Practices + +### Security Considerations + +Always validate and sanitize inputs: + +```rust +#[mcp_tool] +impl AdvancedServer { + /// Secure file access with validation + async fn read_secure_file(&self, path: String) -> Result { + // Prevent directory traversal + if path.contains("..") || path.starts_with("/") { + return Err(std::io::Error::new( + std::io::ErrorKind::PermissionDenied, + "Invalid path" + )); + } + + // Restrict to safe directory + let safe_path = format!("./data/{}", path); + tokio::fs::read_to_string(safe_path).await + } +} +``` + +### Testing Your Server + +Write comprehensive tests for your MCP server: + +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn test_server_functionality() { + let server = AdvancedServer::with_defaults(); + + // Test tools + let result = server.add(2.0, 3.0).await; + assert_eq!(result, 5.0); + + // Test error handling + let error_result = server.process_text("test".to_string(), "invalid".to_string()).await; + assert!(error_result.is_err()); + } +} +``` + +### Deployment Patterns + +Structure your main function for robust deployment: + +```rust +#[tokio::main] +async fn main() -> Result<(), Box> { + // Initialize logging + tracing_subscriber::fmt::init(); + + // Create server instance + let server = AdvancedServer::with_defaults(); + + // Choose transport based on environment + let service = match std::env::var("MCP_TRANSPORT") { + Ok(transport) if transport == "http" => { + let port = std::env::var("MCP_PORT") + .unwrap_or_else(|_| "8080".to_string()) + .parse() + .unwrap_or(8080); + server.serve_http(port).await? + } + _ => server.serve_stdio().await? + }; + + // Handle graceful shutdown + let shutdown = async { + tokio::signal::ctrl_c().await.expect("Failed to listen for Ctrl+C"); + tracing::info!("Shutdown signal received"); + }; + + service.run_with_shutdown(shutdown).await?; + Ok(()) +} +``` + +## Next Steps + +Now that you understand the PulseEngine MCP macro system: + +1. **Explore Examples** - Check out the [examples directory](../examples/) for real-world implementations +2. **Read the Protocol** - Understand the [MCP specification](https://modelcontextprotocol.io/specification/) +3. **Join the Community** - Connect with other MCP developers +4. **Contribute** - Help improve the macro system with feedback and contributions + +### Additional Resources + +- [Macro API Reference](./API_REFERENCE.md) - Complete macro documentation +- [Advanced Patterns](./ADVANCED_PATTERNS.md) - Complex implementation patterns +- [Deployment Guide](./DEPLOYMENT.md) - Production deployment strategies +- [Troubleshooting](./TROUBLESHOOTING.md) - Common issues and solutions + +--- + +Happy building! The PulseEngine MCP macro system makes it easier than ever to create powerful, protocol-compliant MCP servers that work seamlessly with Claude and other AI assistants. \ No newline at end of file diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 00000000..c6fb46c8 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,837 @@ +# PulseEngine MCP Macros: Troubleshooting Guide + +This guide helps diagnose and resolve common issues when building and deploying MCP servers with PulseEngine macros. + +## Compilation Issues + +### Macro Expansion Errors + +**Problem**: Macro expansion fails with cryptic error messages. + +```rust +error: expected identifier, found `async` + --> src/lib.rs:12:5 + | +12 | async fn my_tool(&self) -> String { ... } + | ^^^^^ +``` + +**Common Causes**: +1. Missing `#[mcp_tool]` attribute on impl block +2. Incorrect macro syntax +3. Unsupported method signatures + +**Solutions**: + +```rust +// ❌ Wrong - missing #[mcp_tool] attribute +impl MyServer { + async fn my_tool(&self) -> String { + "result".to_string() + } +} + +// ✅ Correct - with attribute +#[mcp_tool] +impl MyServer { + async fn my_tool(&self) -> String { + "result".to_string() + } +} + +// ❌ Wrong - invalid parameter types +#[mcp_tool] +impl MyServer { + async fn invalid_tool(&self, param: Box) -> String { + // Box doesn't implement Deserialize + "result".to_string() + } +} + +// ✅ Correct - serializable parameters +#[mcp_tool] +impl MyServer { + async fn valid_tool(&self, param: String) -> String { + format!("processed: {}", param) + } +} +``` + +### Type System Errors + +**Problem**: Complex types fail to serialize/deserialize. + +```rust +error[E0277]: the trait bound `CustomType: serde::Deserialize<'_>` is not satisfied +``` + +**Solutions**: + +```rust +use serde::{Deserialize, Serialize}; + +// ❌ Wrong - missing Serialize/Deserialize +struct CustomType { + field: String, +} + +// ✅ Correct - with derives +#[derive(Debug, Clone, Serialize, Deserialize)] +struct CustomType { + field: String, +} + +// For external types, use wrapper types +#[derive(Debug, Clone, Serialize, Deserialize)] +struct WrappedExternalType { + #[serde(flatten)] + inner: ExternalType, +} +``` + +### Lifetime Issues + +**Problem**: Lifetime errors in generated code. + +```rust +error[E0621]: explicit lifetime required in the type of `self` +``` + +**Solutions**: + +```rust +// ❌ Wrong - returning references to local data +#[mcp_tool] +impl MyServer { + async fn bad_tool(&self) -> &str { + let local_string = "temp".to_string(); + &local_string // This won't work + } +} + +// ✅ Correct - return owned data +#[mcp_tool] +impl MyServer { + async fn good_tool(&self) -> String { + "result".to_string() + } +} + +// ✅ Correct - return references to self +#[mcp_tool] +impl MyServer { + async fn reference_tool(&self) -> &str { + &self.static_data // OK if static_data is part of self + } +} +``` + +## Runtime Issues + +### Connection Problems + +**Problem**: Client cannot connect to MCP server. + +**Diagnostic Steps**: + +1. **Check Transport Type**: +```rust +// Verify transport matches client expectations +#[tokio::main] +async fn main() -> Result<(), Box> { + let server = MyServer::with_defaults(); + + // For Claude Desktop - use STDIO + let service = server.serve_stdio().await?; + + // For HTTP clients + // let service = server.serve_http(8080).await?; + + service.run().await?; + Ok(()) +} +``` + +2. **Enable Debug Logging**: +```rust +use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt}; + +#[tokio::main] +async fn main() -> Result<(), Box> { + // Enable debug logging + tracing_subscriber::registry() + .with(tracing_subscriber::EnvFilter::new("debug")) + .with(tracing_subscriber::fmt::layer()) + .init(); + + let server = MyServer::with_defaults(); + let service = server.serve_stdio().await?; + service.run().await?; + Ok(()) +} +``` + +3. **Test with MCP Inspector**: +```bash +# Install MCP Inspector +npm install -g @modelcontextprotocol/inspector + +# Test your server +mcp-inspector path/to/your/server/binary +``` + +### Tool Execution Errors + +**Problem**: Tools fail at runtime with serialization errors. + +```json +{ + "error": { + "code": -32602, + "message": "Invalid params", + "data": "missing field `required_param`" + } +} +``` + +**Solutions**: + +1. **Add Parameter Validation**: +```rust +use serde::{Deserialize, Serialize}; +use validator::{Validate, ValidationError}; + +#[derive(Debug, Deserialize, Validate)] +struct ToolParams { + #[validate(length(min = 1, max = 100))] + name: String, + + #[validate(range(min = 0, max = 1000))] + count: Option, + + #[validate(email)] + email: Option, +} + +#[mcp_tool] +impl MyServer { + /// Tool with validation + async fn validated_tool(&self, params: ToolParams) -> Result { + // Validate input + params.validate()?; + + // Process validated data + Ok(format!("Processed: {}", params.name)) + } +} +``` + +2. **Improve Error Messages**: +```rust +#[derive(Debug, thiserror::Error)] +enum ToolError { + #[error("Invalid input parameter '{field}': {reason}")] + InvalidParameter { field: String, reason: String }, + + #[error("Resource not found: {resource_id}")] + ResourceNotFound { resource_id: String }, + + #[error("Operation failed: {details}")] + OperationFailed { details: String }, +} + +#[mcp_tool] +impl MyServer { + async fn error_handling_tool(&self, id: String) -> Result { + if id.is_empty() { + return Err(ToolError::InvalidParameter { + field: "id".to_string(), + reason: "cannot be empty".to_string(), + }); + } + + // Simulate resource lookup + if id == "missing" { + return Err(ToolError::ResourceNotFound { resource_id: id }); + } + + Ok(format!("Found resource: {}", id)) + } +} +``` + +### Resource Access Issues + +**Problem**: Resource URIs fail to match or parse incorrectly. + +**Diagnostic Steps**: + +1. **Test URI Templates**: +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_uri_template_parsing() { + // Test URI template matching + let uri = "file:///home/user/document.txt"; + let template = "file://{path}"; + + // Manual verification of template parsing + assert!(uri.starts_with("file://")); + + let path = uri.strip_prefix("file://").unwrap(); + assert_eq!(path, "/home/user/document.txt"); + } + + #[tokio::test] + async fn test_resource_access() { + let server = MyServer::with_defaults(); + + // Test with valid URI + let result = server.my_resource("valid_path".to_string()).await; + assert!(result.is_ok()); + + // Test with invalid URI + let result = server.my_resource("".to_string()).await; + assert!(result.is_err()); + } +} +``` + +2. **Debug URI Template Parsing**: +```rust +#[mcp_resource(uri_template = "file://{path}")] +impl MyServer { + /// Resource with debug logging + async fn debug_resource(&self, path: String) -> Result { + tracing::debug!("Resource accessed with path: {}", path); + + // Validate path + if path.is_empty() { + tracing::error!("Empty path provided"); + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Path cannot be empty" + )); + } + + // Check file existence + if !std::path::Path::new(&path).exists() { + tracing::warn!("File does not exist: {}", path); + return Err(std::io::Error::new( + std::io::ErrorKind::NotFound, + format!("File not found: {}", path) + )); + } + + tokio::fs::read_to_string(&path).await + } +} +``` + +## Performance Issues + +### Memory Usage Problems + +**Problem**: Server consumes excessive memory or has memory leaks. + +**Diagnostic Tools**: + +1. **Add Memory Monitoring**: +```rust +use sysinfo::{System, SystemExt}; + +#[derive(Clone)] +struct MemoryMonitor { + system: Arc>, +} + +impl MemoryMonitor { + fn new() -> Self { + Self { + system: Arc::new(Mutex::new(System::new_all())), + } + } + + async fn get_memory_usage(&self) -> (u64, u64) { + let mut system = self.system.lock().await; + system.refresh_memory(); + (system.used_memory(), system.total_memory()) + } +} + +#[mcp_tool] +impl MyServer { + /// Memory usage diagnostic tool + async fn memory_usage(&self) -> Result { + let (used, total) = self.memory_monitor.get_memory_usage().await; + let usage_percent = (used as f64 / total as f64) * 100.0; + + Ok(serde_json::json!({ + "used_bytes": used, + "total_bytes": total, + "usage_percent": usage_percent, + "timestamp": chrono::Utc::now().to_rfc3339() + })) + } +} +``` + +2. **Use Memory Profiling**: +```toml +# Cargo.toml +[dependencies] +jemalloc = { version = "0.5", features = ["profiling"], optional = true } + +[features] +jemalloc = ["dep:jemalloc"] +``` + +```rust +#[cfg(feature = "jemalloc")] +use jemalloc_ctl::{stats, epoch}; + +#[mcp_tool] +impl MyServer { + /// Memory profiling tool (requires jemalloc feature) + #[cfg(feature = "jemalloc")] + async fn memory_profile(&self) -> Result { + epoch::advance().unwrap(); + + let allocated = stats::allocated::read().unwrap(); + let resident = stats::resident::read().unwrap(); + let retained = stats::retained::read().unwrap(); + + Ok(serde_json::json!({ + "allocated": allocated, + "resident": resident, + "retained": retained, + "fragmentation_ratio": resident as f64 / allocated as f64 + })) + } +} +``` + +### Connection Pool Issues + +**Problem**: Database connection pool exhaustion or timeouts. + +**Solutions**: + +1. **Configure Pool Properly**: +```rust +use deadpool_postgres::{Config, Pool}; + +async fn create_optimized_pool() -> Result { + let mut config = Config::new(); + config.host = Some("localhost".to_string()); + config.user = Some("postgres".to_string()); + config.dbname = Some("mydb".to_string()); + + // Pool configuration + config.manager = Some(deadpool_postgres::ManagerConfig { + recycling_method: deadpool_postgres::RecyclingMethod::Fast, + }); + + config.pool = Some(deadpool::managed::PoolConfig { + max_size: 20, // Adjust based on your needs + timeouts: deadpool::managed::Timeouts { + wait: Some(std::time::Duration::from_secs(30)), + create: Some(std::time::Duration::from_secs(30)), + recycle: Some(std::time::Duration::from_secs(30)), + }, + }); + + config.create_pool(Some(deadpool_postgres::Runtime::Tokio1), tokio_postgres::NoTls) +} +``` + +2. **Add Connection Monitoring**: +```rust +#[mcp_tool] +impl MyServer { + /// Database pool status + async fn pool_status(&self) -> Result { + let status = self.db_pool.status(); + + Ok(serde_json::json!({ + "size": status.size, + "available": status.available, + "waiting": status.waiting, + "max_size": status.max_size + })) + } +} +``` + +3. **Implement Connection Health Checks**: +```rust +use tokio::time::{interval, Duration}; + +async fn connection_health_monitor(pool: Pool) { + let mut interval = interval(Duration::from_secs(60)); + + loop { + interval.tick().await; + + match pool.get().await { + Ok(conn) => { + match conn.simple_query("SELECT 1").await { + Ok(_) => tracing::debug!("Database connection healthy"), + Err(e) => tracing::error!("Database health check failed: {}", e), + } + } + Err(e) => tracing::error!("Failed to get database connection: {}", e), + } + } +} +``` + +## Configuration Issues + +### Environment Variable Problems + +**Problem**: Configuration values not loading correctly from environment. + +**Solutions**: + +1. **Add Configuration Validation**: +```rust +use config::{Config, ConfigError, Environment, File}; + +#[derive(Debug, serde::Deserialize)] +struct ServerConfig { + database_url: String, + redis_url: String, + api_key: Option, + log_level: String, +} + +impl ServerConfig { + fn from_env() -> Result { + let config = Config::builder() + .add_source(File::with_name("config/default").required(false)) + .add_source(Environment::with_prefix("MYAPP").separator("_")) + .build()?; + + let config: Self = config.try_deserialize()?; + config.validate()?; + Ok(config) + } + + fn validate(&self) -> Result<(), ConfigError> { + if self.database_url.is_empty() { + return Err(ConfigError::Message("DATABASE_URL is required".into())); + } + + if !self.database_url.starts_with("postgresql://") { + return Err(ConfigError::Message("DATABASE_URL must be a PostgreSQL URL".into())); + } + + match self.log_level.as_str() { + "trace" | "debug" | "info" | "warn" | "error" => {} + _ => return Err(ConfigError::Message("Invalid log level".into())), + } + + Ok(()) + } +} +``` + +2. **Add Configuration Debug Tool**: +```rust +#[mcp_tool] +impl MyServer { + /// Show current configuration (sanitized) + async fn show_config(&self) -> Result { + let config = &self.config; + + Ok(serde_json::json!({ + "database_url": mask_sensitive_info(&config.database_url), + "redis_url": mask_sensitive_info(&config.redis_url), + "log_level": config.log_level, + "api_key_configured": config.api_key.is_some(), + })) + } +} + +fn mask_sensitive_info(url: &str) -> String { + if let Ok(parsed) = url::Url::parse(url) { + let mut masked = parsed.clone(); + if masked.password().is_some() { + let _ = masked.set_password(Some("***")); + } + masked.to_string() + } else { + "invalid_url".to_string() + } +} +``` + +### Authentication Issues + +**Problem**: API key authentication failing. + +**Solutions**: + +1. **Add Authentication Debugging**: +```rust +use pulseengine_mcp_auth::{AuthManager, AuthError}; + +#[derive(Clone)] +struct DebuggingAuthManager { + inner: AuthManager, +} + +impl DebuggingAuthManager { + async fn verify_api_key(&self, key: &str) -> Result { + tracing::debug!("Verifying API key: {}***", &key[..4.min(key.len())]); + + let result = self.inner.verify_api_key(key).await; + + match &result { + Ok(valid) => tracing::debug!("API key validation result: {}", valid), + Err(e) => tracing::error!("API key validation error: {}", e), + } + + result + } +} + +#[mcp_tool] +impl MyServer { + /// Test API key validation + async fn test_auth(&self, api_key: String) -> Result { + let is_valid = self.auth_manager.verify_api_key(&api_key).await?; + + Ok(serde_json::json!({ + "valid": is_valid, + "key_prefix": &api_key[..4.min(api_key.len())], + "timestamp": chrono::Utc::now().to_rfc3339() + })) + } +} +``` + +## Deployment Issues + +### Docker Container Problems + +**Problem**: Server fails to start in Docker container. + +**Common Issues and Solutions**: + +1. **Port Binding Issues**: +```dockerfile +# ❌ Wrong - binding to localhost only +EXPOSE 8080 +CMD ["./server", "--bind", "127.0.0.1:8080"] + +# ✅ Correct - binding to all interfaces +EXPOSE 8080 +CMD ["./server", "--bind", "0.0.0.0:8080"] +``` + +2. **File Permission Issues**: +```dockerfile +# Add proper user setup +RUN useradd -r -s /bin/false -u 1001 appuser +RUN mkdir -p /app/data && chown -R appuser:appuser /app +USER appuser +``` + +3. **Resource Limits**: +```yaml +# docker-compose.yml +services: + mcp-server: + deploy: + resources: + limits: + memory: 512M + cpus: '0.5' + reservations: + memory: 256M + cpus: '0.25' +``` + +### Kubernetes Deployment Issues + +**Problem**: Pods failing health checks or crashing. + +**Solutions**: + +1. **Add Comprehensive Health Checks**: +```rust +#[mcp_tool] +impl MyServer { + /// Kubernetes readiness probe + async fn ready(&self) -> Result { + // Check database connectivity + if let Err(e) = self.db_pool.get().await { + return Err(std::io::Error::new( + std::io::ErrorKind::Other, + format!("Database not ready: {}", e) + )); + } + + // Check Redis connectivity + if let Err(e) = self.redis_pool.get().await { + return Err(std::io::Error::new( + std::io::ErrorKind::Other, + format!("Redis not ready: {}", e) + )); + } + + Ok(serde_json::json!({"status": "ready"})) + } + + /// Kubernetes liveness probe + async fn alive(&self) -> Result { + // Simple alive check + Ok(serde_json::json!({ + "status": "alive", + "timestamp": chrono::Utc::now().to_rfc3339() + })) + } +} +``` + +2. **Add Resource Monitoring**: +```yaml +apiVersion: v1 +kind: Pod +spec: + containers: + - name: mcp-server + resources: + requests: + memory: "128Mi" + cpu: "100m" + limits: + memory: "512Mi" + cpu: "500m" + livenessProbe: + httpGet: + path: /alive + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + readinessProbe: + httpGet: + path: /ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 +``` + +## Debugging Tools + +### Built-in Diagnostic Tools + +Add these diagnostic tools to any server for troubleshooting: + +```rust +#[mcp_tool] +impl MyServer { + /// System information + async fn system_info(&self) -> Result { + use sysinfo::{System, SystemExt}; + + let mut system = System::new_all(); + system.refresh_all(); + + Ok(serde_json::json!({ + "hostname": system.host_name(), + "os": system.long_os_version(), + "kernel": system.kernel_version(), + "cpu_count": system.processors().len(), + "total_memory": system.total_memory(), + "used_memory": system.used_memory(), + "total_swap": system.total_swap(), + "used_swap": system.used_swap(), + "uptime": system.uptime(), + })) + } + + /// Process information + async fn process_info(&self) -> Result { + use sysinfo::{Pid, ProcessExt, System, SystemExt}; + + let mut system = System::new_all(); + system.refresh_all(); + + let pid = Pid::from(std::process::id() as usize); + if let Some(process) = system.process(pid) { + Ok(serde_json::json!({ + "pid": process.pid().as_u32(), + "name": process.name(), + "memory": process.memory(), + "virtual_memory": process.virtual_memory(), + "cpu_usage": process.cpu_usage(), + "start_time": process.start_time(), + "run_time": process.run_time(), + })) + } else { + Err(std::io::Error::new( + std::io::ErrorKind::NotFound, + "Process not found" + )) + } + } + + /// Connection status + async fn connection_status(&self) -> Result { + let db_status = self.db_pool.status(); + let redis_status = "connected"; // Implement actual Redis status check + + Ok(serde_json::json!({ + "database": { + "size": db_status.size, + "available": db_status.available, + "waiting": db_status.waiting, + }, + "redis": { + "status": redis_status, + }, + "timestamp": chrono::Utc::now().to_rfc3339() + })) + } +} +``` + +### Log Analysis + +Configure structured logging for better debugging: + +```rust +use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt}; + +pub fn init_logging() -> Result<(), Box> { + tracing_subscriber::registry() + .with(tracing_subscriber::EnvFilter::new( + std::env::var("RUST_LOG").unwrap_or_else(|_| { + "myapp=debug,pulseengine_mcp=debug,tower_http=debug".into() + }) + )) + .with( + tracing_subscriber::fmt::layer() + .with_target(true) + .with_thread_ids(true) + .with_file(true) + .with_line_number(true) + .json() // Use JSON for structured logging + ) + .try_init()?; + + Ok(()) +} +``` + +This troubleshooting guide covers the most common issues encountered when building and deploying MCP servers with PulseEngine macros. Keep this guide handy during development and deployment phases. \ No newline at end of file diff --git a/examples/hello-world-macros/Cargo.toml b/examples/hello-world-macros/Cargo.toml index ec65f6a3..cc2e8b69 100644 --- a/examples/hello-world-macros/Cargo.toml +++ b/examples/hello-world-macros/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "hello-world-macros" version = "0.1.0" -edition = "2021" +edition = "2024" description = "Hello World MCP Server using PulseEngine macros" [features] @@ -24,6 +24,7 @@ serde_json = "1.0" thiserror = "1.0" tracing = "0.1" tracing-subscriber = { version = "0.3", features = ["env-filter"] } +chrono = { version = "0.4", features = ["serde"] } [[bin]] name = "hello-world-macros" diff --git a/examples/hello-world-macros/src/main.rs b/examples/hello-world-macros/src/main.rs index 757bad02..9275b031 100644 --- a/examples/hello-world-macros/src/main.rs +++ b/examples/hello-world-macros/src/main.rs @@ -1,205 +1,379 @@ -//! Hello World MCP Server Example Using Macros -//! -//! This demonstrates how the macro system simplifies MCP server development -//! while maintaining enterprise capabilities. -//! -//! This example shows the macro-generated server infrastructure without -//! conflicting manual implementations. - -use pulseengine_mcp_macros::mcp_server; -use pulseengine_mcp_protocol::{CallToolRequestParam, CallToolResult, Content, Tool}; -use pulseengine_mcp_server::McpBackend; +//! Enhanced Hello World MCP Server with Comprehensive Features + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; use serde_json::json; +use std::collections::HashMap; use std::sync::{ + Arc, RwLock, atomic::{AtomicU64, Ordering}, - Arc, }; -/// A simple greeting server that showcases the macro-driven API +#[derive(Clone, Debug)] +struct GreetingRecord { + id: u64, + name: String, + greeting: String, + language: String, + timestamp: String, +} + +/// Enhanced greeting server demonstrating comprehensive macro capabilities /// -/// This server demonstrates: -/// - Automatic backend trait implementation via #[mcp_server] -/// - Type-safe error handling -/// - Fluent builder API for server creation -/// - Smart defaults with enterprise capabilities -/// - Manual tool integration (until automatic tool discovery is implemented) +/// This server showcases: +/// - #[mcp_server] for automatic server setup with application-specific configuration +/// - #[mcp_tools] for bulk tool registration from impl blocks +/// - Advanced greeting functionality with templates and history +/// - Multi-language support with cultural customization +/// - Comprehensive statistics and search capabilities #[mcp_server( - name = "Hello World Macros", - description = "Demonstrates the new macro system" + name = "Enhanced Hello World Server", + app_name = "hello-world-enhanced", + version = "2.0.0", + description = "Comprehensive demo of MCP macro capabilities with tools, history, and customization" )] #[derive(Clone)] -struct HelloWorldMacros { - #[allow(dead_code)] +pub struct EnhancedHelloWorldServer { greeting_count: Arc, + greeting_history: Arc>>, + templates: Arc>>, } -impl Default for HelloWorldMacros { +impl Default for EnhancedHelloWorldServer { fn default() -> Self { + let mut templates = HashMap::new(); + templates.insert( + "formal".to_string(), + "Good day, {name}. I hope this message finds you well.".to_string(), + ); + templates.insert( + "casual".to_string(), + "Hey {name}! What's up? 😊".to_string(), + ); + templates.insert( + "enthusiastic".to_string(), + "WOW! Hi there {name}! So excited to meet you! 🎉".to_string(), + ); + templates.insert( + "professional".to_string(), + "Dear {name}, thank you for connecting with our service.".to_string(), + ); + templates.insert( + "friendly".to_string(), + "Hi {name}! Nice to meet you! 🤝".to_string(), + ); + Self { greeting_count: Arc::new(AtomicU64::new(0)), + greeting_history: Arc::new(RwLock::new(Vec::new())), + templates: Arc::new(RwLock::new(templates)), } } } -// Business logic methods - these would be exposed as tools in a complete implementation -impl HelloWorldMacros { - /// Say hello to someone with a customizable greeting - #[allow(dead_code)] - pub async fn say_hello(&self, name: String, greeting: Option) -> String { - let greeting = greeting.unwrap_or_else(|| "Hello".to_string()); +/// All tools are automatically registered via the #[mcp_tools] macro +/// This demonstrates the complete tool functionality with comprehensive features +#[mcp_tools] +impl EnhancedHelloWorldServer { + /// Generate a personalized greeting with extensive customization options + /// + /// This tool supports multiple greeting types, languages, and styling options. + /// It maintains a complete history of all greetings for analytics and personalization. + /// + /// # Parameters + /// - name: The name of the person to greet (required) + /// - greeting_type: Style of greeting (casual, formal, enthusiastic, professional, friendly) + /// - language: Language code (en, es, fr, de, ja) - defaults to English + /// - include_emoji: Whether to include emoji decorations (default: true) + /// + /// # Returns + /// A personalized greeting string with unique numbering + pub async fn say_hello( + &self, + name: String, + greeting_type: Option, + language: Option, + include_emoji: Option, + ) -> String { + let greeting_type = greeting_type.unwrap_or_else(|| "casual".to_string()); + let language = language.unwrap_or_else(|| "en".to_string()); + let include_emoji = include_emoji.unwrap_or(true); + let count = self.greeting_count.fetch_add(1, Ordering::Relaxed) + 1; + // Get greeting template + let templates = self.templates.read().unwrap(); + let template = templates + .get(&greeting_type) + .unwrap_or(&"Hello {name}!".to_string()) + .clone(); + drop(templates); + + // Generate greeting based on template + let mut greeting = template.replace("{name}", &name); + + // Apply language-specific customizations + match language.as_str() { + "es" => greeting = format!("¡{}!", greeting.trim_end_matches('!')), + "fr" => greeting = format!("{}!", greeting.trim_end_matches('!')), + "de" => greeting = greeting.replace("Hello", "Hallo").replace("Hi", "Hallo"), + "ja" => greeting = format!("{name}さん、こんにちは！"), + _ => {} // English default + } + + // Add emoji decoration if requested + if include_emoji { + let emoji = match greeting_type.as_str() { + "formal" => "🤝", + "casual" => "👋", + "enthusiastic" => "🎉", + "professional" => "💼", + "friendly" => "😊", + _ => "👋", + }; + greeting = format!("{greeting} {emoji}"); + } + + // Record the greeting for history and analytics + let record = GreetingRecord { + id: count, + name: name.clone(), + greeting: greeting.clone(), + language, + timestamp: chrono::Utc::now().to_rfc3339(), + }; + + let mut history = self.greeting_history.write().unwrap(); + history.push(record); + tracing::info!( tool = "say_hello", name = %name, - greeting = %greeting, + greeting_type = %greeting_type, count = count, - "Generated greeting" + "Generated personalized greeting" ); - format!("{greeting}, {name}! 👋 (Greeting #{count})") + format!("{greeting} (Greeting #{count})") } - /// Get the total number of greetings sent - #[allow(dead_code)] - pub async fn count_greetings(&self) -> u64 { + /// Get comprehensive greeting statistics and analytics + /// + /// Returns detailed statistics about greeting usage including: + /// - Total number of greetings generated + /// - Language distribution breakdown + /// - Recent greeting history (last 5) + /// - Available template options + pub fn get_greeting_stats(&self) -> serde_json::Value { let count = self.greeting_count.load(Ordering::Relaxed); + let history = self.greeting_history.read().unwrap(); + + let mut language_counts = HashMap::new(); + let mut greeting_type_counts = HashMap::new(); + let mut recent_greetings = Vec::new(); + + // Analyze recent greetings for patterns + for record in history.iter().rev().take(5) { + *language_counts.entry(record.language.clone()).or_insert(0) += 1; + recent_greetings.push(json!({ + "id": record.id, + "name": record.name, + "greeting": record.greeting, + "language": record.language, + "timestamp": record.timestamp + })); + } + + // Count greeting types based on emoji patterns (simple heuristic) + for record in history.iter() { + let greeting_type = if record.greeting.contains("🤝") { + "formal" + } else if record.greeting.contains("🎉") { + "enthusiastic" + } else if record.greeting.contains("💼") { + "professional" + } else if record.greeting.contains("😊") { + "friendly" + } else { + "casual" + }; + *greeting_type_counts + .entry(greeting_type.to_string()) + .or_insert(0) += 1; + } tracing::info!( - tool = "count_greetings", - count = count, - "Retrieved greeting count" + tool = "get_greeting_stats", + total_count = count, + unique_languages = language_counts.len(), + "Retrieved comprehensive greeting statistics" ); - count + json!({ + "total_greetings": count, + "language_distribution": language_counts, + "greeting_type_distribution": greeting_type_counts, + "recent_greetings": recent_greetings, + "available_templates": self.templates.read().unwrap().keys().collect::>(), + "statistics_generated_at": chrono::Utc::now().to_rfc3339() + }) } - /// Generate a random greeting in different languages - #[allow(dead_code)] - pub async fn random_greeting(&self) -> String { - let greetings = [ - "Hello", - "Hola", - "Bonjour", - "Guten Tag", - "Ciao", - "こんにちは", - "안녕하세요", - "Привет", - ]; - - let random_index = self.greeting_count.load(Ordering::Relaxed) as usize % greetings.len(); - let greeting = greetings[random_index]; + /// Add a custom greeting template with validation + /// + /// Allows users to create personalized greeting templates that can be used + /// with the say_hello tool. Templates must contain the {name} placeholder. + /// + /// # Parameters + /// - template_name: Unique name for the template + /// - template_text: Template text with {name} placeholder + /// + /// # Returns + /// Success confirmation message + pub fn add_greeting_template( + &self, + template_name: String, + template_text: String, + ) -> Result { + if template_name.is_empty() || template_text.is_empty() { + return Err("Template name and text cannot be empty".to_string()); + } + + if !template_text.contains("{name}") { + return Err("Template must contain {name} placeholder".to_string()); + } + + let mut templates = self.templates.write().unwrap(); + let is_update = templates.contains_key(&template_name); + templates.insert(template_name.clone(), template_text.clone()); tracing::info!( - tool = "random_greeting", - greeting = %greeting, - "Generated random greeting" + tool = "add_greeting_template", + template_name = %template_name, + is_update = is_update, + "Added/updated custom greeting template" ); - greeting.to_string() + if is_update { + Ok(format!("Successfully updated template: {template_name}")) + } else { + Ok(format!("Successfully added new template: {template_name}")) + } } -} -// Override the tool registry methods to wire up our custom tools using the trait -impl McpToolProvider for HelloWorldMacros { - /// Register all tools - manually wired until automatic discovery is implemented - fn register_tools(&self, tools: &mut Vec) { - tools.push(Tool { - name: "say_hello".to_string(), - description: "Say hello to someone with a customizable greeting".to_string(), - input_schema: json!({ - "type": "object", - "properties": { - "name": {"type": "string", "description": "Name to greet"}, - "greeting": {"type": "string", "description": "Custom greeting (optional)"} - }, - "required": ["name"] - }), - output_schema: None, - }); - - tools.push(Tool { - name: "count_greetings".to_string(), - description: "Get the total number of greetings sent".to_string(), - input_schema: json!({"type": "object", "properties": {}}), - output_schema: None, - }); - - tools.push(Tool { - name: "random_greeting".to_string(), - description: "Generate a random greeting in different languages".to_string(), - input_schema: json!({"type": "object", "properties": {}}), - output_schema: None, - }); + /// Search greeting history with advanced filtering + /// + /// Provides powerful search capabilities across the greeting history. + /// Searches through names, greeting text, and languages. + /// + /// # Parameters + /// - query: Search term to look for + /// - limit: Maximum number of results to return (default: 10) + /// + /// # Returns + /// Array of matching greeting records with full details + pub fn search_greetings(&self, query: String, limit: Option) -> Vec { + let history = self.greeting_history.read().unwrap(); + let limit = limit.unwrap_or(10) as usize; + let query_lower = query.to_lowercase(); + + let results: Vec = history + .iter() + .filter(|record| { + record.name.to_lowercase().contains(&query_lower) + || record.greeting.to_lowercase().contains(&query_lower) + || record.language.to_lowercase().contains(&query_lower) + }) + .rev() // Most recent first + .take(limit) + .map(|record| { + let days_ago = { + let timestamp = chrono::DateTime::parse_from_rfc3339(&record.timestamp) + .unwrap_or_else(|_| chrono::Utc::now().into()); + let now = chrono::Utc::now(); + (now - timestamp.with_timezone(&chrono::Utc)).num_days() + }; + json!({ + "id": record.id, + "name": record.name, + "greeting": record.greeting, + "language": record.language, + "timestamp": record.timestamp, + "days_ago": days_ago + }) + }) + .collect(); + + tracing::info!( + tool = "search_greetings", + query = %query, + results_count = results.len(), + "Searched greeting history with advanced filtering" + ); + + results } - /// Dispatch tool calls to appropriate handlers - fn dispatch_tool_call( - &self, - request: CallToolRequestParam, - ) -> std::pin::Pin< - Box< - dyn std::future::Future< - Output = Result, - > + Send - + '_, - >, - > { - Box::pin(async move { - match request.name.as_str() { - "say_hello" => { - let args = request.arguments.unwrap_or_default(); - let name = args - .get("name") - .and_then(|v| v.as_str()) - .ok_or_else(|| { - pulseengine_mcp_protocol::Error::invalid_params("name is required") - })? - .to_string(); - let greeting = args - .get("greeting") - .and_then(|v| v.as_str()) - .map(|s| s.to_string()); - - let result = self.say_hello(name, greeting).await; - - Ok(CallToolResult { - content: vec![Content::text(result)], - is_error: Some(false), - structured_content: None, - }) - } - "count_greetings" => { - let result = self.count_greetings().await; - - Ok(CallToolResult { - content: vec![Content::text(format!("Total greetings: {result}"))], - is_error: Some(false), - structured_content: None, - }) - } - "random_greeting" => { - let result = self.random_greeting().await; - - Ok(CallToolResult { - content: vec![Content::text(result)], - is_error: Some(false), - structured_content: None, - }) + /// Get current server status and performance metrics + /// + /// Returns comprehensive information about the server's current state, + /// including uptime, performance metrics, and operational statistics. + pub fn get_server_status(&self) -> serde_json::Value { + let count = self.greeting_count.load(Ordering::Relaxed); + let history = self.greeting_history.read().unwrap(); + let templates = self.templates.read().unwrap(); + + // Calculate some basic metrics + let avg_greetings_per_minute = if history.len() >= 2 { + let first = history.first().unwrap(); + let last = history.last().unwrap(); + + if let (Ok(first_time), Ok(last_time)) = ( + chrono::DateTime::parse_from_rfc3339(&first.timestamp), + chrono::DateTime::parse_from_rfc3339(&last.timestamp), + ) { + let duration_mins = (last_time - first_time).num_minutes() as f64; + if duration_mins > 0.0 { + history.len() as f64 / duration_mins + } else { + 0.0 } - _ => Err(pulseengine_mcp_protocol::Error::invalid_params(format!( - "Unknown tool: {}", - request.name - ))), + } else { + 0.0 } + } else { + 0.0 + }; + + json!({ + "status": "running", + "server_name": "Enhanced Hello World Server", + "version": "2.0.0", + "app_name": "hello-world-enhanced", + "current_time": chrono::Utc::now().to_rfc3339(), + "total_greetings": count, + "total_history_records": history.len(), + "available_templates": templates.len(), + "template_names": templates.keys().collect::>(), + "performance_metrics": { + "average_greetings_per_minute": avg_greetings_per_minute, + "memory_efficiency": "optimized", + "concurrent_safety": "thread_safe" + }, + "features": [ + "multi_language_support", + "custom_templates", + "history_tracking", + "advanced_search", + "statistics_analytics", + "emoji_decorations" + ] }) } } #[tokio::main] async fn main() -> std::result::Result<(), Box> { - // Initialize logging + // Initialize comprehensive logging tracing_subscriber::fmt() .with_env_filter( tracing_subscriber::EnvFilter::try_from_default_env() @@ -207,27 +381,34 @@ async fn main() -> std::result::Result<(), Box> { ) .init(); - tracing::info!("🚀 Starting Hello World Macros MCP Server"); + tracing::info!("🚀 Starting Enhanced Hello World MCP Server"); + tracing::info!("📦 App Name: hello-world-enhanced"); + tracing::info!("🔧 Features: Advanced tools with comprehensive functionality"); + tracing::info!("🔐 Authentication: Application-specific configuration"); - // This demonstrates the macro-generated fluent API - // The #[mcp_server] macro generates: - // - Complete McpBackend implementation - // - Error types and conversions - // - Configuration management - // - Fluent builder methods like .serve_stdio() - let server = HelloWorldMacros::with_defaults().serve_stdio().await?; + // Create and configure the server with application-specific settings + let server = EnhancedHelloWorldServer::with_defaults() + .serve_stdio() + .await?; - tracing::info!("✅ Hello World Macros MCP Server started successfully"); - tracing::info!("💡 Server demonstrates macro-generated infrastructure"); + tracing::info!("✅ Enhanced Hello World MCP Server started successfully"); + tracing::info!("🛠️ Available Tools:"); + tracing::info!(" • say_hello - Personalized greetings with multi-language support"); + tracing::info!(" • get_greeting_stats - Comprehensive analytics and statistics"); + tracing::info!(" • add_greeting_template - Custom template management"); + tracing::info!(" • search_greetings - Advanced history search capabilities"); + tracing::info!(" • get_server_status - Server status and performance metrics"); tracing::info!("🔗 Connect using any MCP client via stdio transport"); - tracing::info!("📝 Note: Tool implementations would use #[mcp_tool] in practice"); + tracing::info!( + "📚 Documentation: This server demonstrates the full power of PulseEngine MCP macros" + ); - // Run the server - this uses the macro-generated service wrapper + // Run the server with automatic capability detection server .run() .await .map_err(|e| Box::new(e) as Box)?; - tracing::info!("👋 Hello World Macros MCP Server stopped"); + tracing::info!("👋 Enhanced Hello World MCP Server stopped gracefully"); Ok(()) } diff --git a/integration-tests/src/cli_server_integration.rs b/integration-tests/src/cli_server_integration.rs index 04109e21..060750d3 100644 --- a/integration-tests/src/cli_server_integration.rs +++ b/integration-tests/src/cli_server_integration.rs @@ -2,7 +2,7 @@ use crate::test_utils::*; use async_trait::async_trait; -use pulseengine_mcp_cli::{config::create_server_info, CliError}; +use pulseengine_mcp_cli::{CliError, config::create_server_info}; use pulseengine_mcp_protocol::*; use pulseengine_mcp_server::backend::{BackendError, McpBackend}; use pulseengine_mcp_transport::TransportConfig; @@ -354,11 +354,13 @@ async fn test_cli_server_integration_with_backend() { .unwrap(); assert_eq!(read_result.contents.len(), 1); - assert!(read_result.contents[0] - .text - .as_ref() - .unwrap() - .contains("CLI Integration Backend")); + assert!( + read_result.contents[0] + .text + .as_ref() + .unwrap() + .contains("CLI Integration Backend") + ); } #[tokio::test] diff --git a/integration-tests/src/end_to_end_scenarios.rs b/integration-tests/src/end_to_end_scenarios.rs index 5eae456f..552c6cc1 100644 --- a/integration-tests/src/end_to_end_scenarios.rs +++ b/integration-tests/src/end_to_end_scenarios.rs @@ -17,8 +17,8 @@ use std::collections::HashMap; use std::error::Error as StdError; use std::fmt; use std::sync::{ - atomic::{AtomicU64, Ordering}, Arc, + atomic::{AtomicU64, Ordering}, }; use std::time::{Duration, SystemTime, UNIX_EPOCH}; @@ -576,7 +576,7 @@ async fn test_complete_e2e_scenario() { // Test server creation and configuration let server_info = server.get_server_info(); assert_eq!(server_info.server_info.name, "MCP Server"); // Server uses config name, not backend name - // Verify we can get server info - the specific capabilities depend on server config vs backend + // Verify we can get server info - the specific capabilities depend on server config vs backend // Test health check let health = server.health_check().await.unwrap(); diff --git a/integration-tests/src/lib.rs b/integration-tests/src/lib.rs index 49711c5d..832d8a11 100644 --- a/integration-tests/src/lib.rs +++ b/integration-tests/src/lib.rs @@ -14,7 +14,7 @@ pub mod transport_server_integration; /// Common test utilities for integration tests pub mod test_utils { - use pulseengine_mcp_auth::{config::StorageConfig, AuthConfig}; + use pulseengine_mcp_auth::{AuthConfig, config::StorageConfig}; use pulseengine_mcp_monitoring::MonitoringConfig; use pulseengine_mcp_security::SecurityConfig; use std::time::Duration; diff --git a/mcp-auth/src/bin/mcp-auth-cli.rs b/mcp-auth/src/bin/mcp-auth-cli.rs index 61c4fd5a..53c0dc2d 100644 --- a/mcp-auth/src/bin/mcp-auth-cli.rs +++ b/mcp-auth/src/bin/mcp-auth-cli.rs @@ -7,12 +7,12 @@ use chrono::Utc; use clap::{Parser, Subcommand}; use pulseengine_mcp_auth::{ - config::StorageConfig, - consent::manager::ConsentRequest, - vault::{VaultConfig, VaultIntegration}, AuthConfig, AuthenticationManager, ConsentConfig, ConsentManager, ConsentType, KeyCreationRequest, LegalBasis, MemoryConsentStorage, PerformanceConfig, PerformanceTest, Role, TestOperation, ValidationConfig, + config::StorageConfig, + consent::manager::ConsentRequest, + vault::{VaultConfig, VaultIntegration}, }; use std::path::PathBuf; use std::process; @@ -2599,7 +2599,8 @@ fn print_benchmark_results(results: &pulseengine_mcp_auth::PerformanceResults, o } fn generate_text_report(results: &pulseengine_mcp_auth::PerformanceResults) -> String { - format!("Performance Test Report\n{}\n\nTest executed on: {}\nDuration: {:.1} seconds\nConcurrent Users: {}\n\nOverall Results:\n- Total Requests: {}\n- Success Rate: {:.1}%\n- Overall RPS: {:.1}\n- Peak RPS: {:.1}\n\nResource Usage:\n- Peak Memory: {:.1} MB\n- Peak CPU: {:.1}%\n- Threads: {}\n", + format!( + "Performance Test Report\n{}\n\nTest executed on: {}\nDuration: {:.1} seconds\nConcurrent Users: {}\n\nOverall Results:\n- Total Requests: {}\n- Success Rate: {:.1}%\n- Overall RPS: {:.1}\n- Peak RPS: {:.1}\n\nResource Usage:\n- Peak Memory: {:.1} MB\n- Peak CPU: {:.1}%\n- Threads: {}\n", "=".repeat(50), results.start_time.format("%Y-%m-%d %H:%M:%S UTC"), results.test_duration_secs, diff --git a/mcp-auth/src/bin/mcp-auth-init.rs b/mcp-auth/src/bin/mcp-auth-init.rs index fca63a27..73b3b9bd 100644 --- a/mcp-auth/src/bin/mcp-auth-init.rs +++ b/mcp-auth/src/bin/mcp-auth-init.rs @@ -5,11 +5,11 @@ use clap::{Parser, Subcommand}; use colored::*; -use dialoguer::{theme::ColorfulTheme, Confirm, Input, MultiSelect, Select}; +use dialoguer::{Confirm, Input, MultiSelect, Select, theme::ColorfulTheme}; use pulseengine_mcp_auth::{ - config::StorageConfig, - setup::{validator, SetupBuilder}, RoleRateLimitConfig, ValidationConfig, + config::StorageConfig, + setup::{SetupBuilder, validator}, }; use std::path::PathBuf; use std::process; diff --git a/mcp-auth/src/bin/mcp-auth-setup.rs b/mcp-auth/src/bin/mcp-auth-setup.rs index ddbd66ab..9cc9ec6f 100644 --- a/mcp-auth/src/bin/mcp-auth-setup.rs +++ b/mcp-auth/src/bin/mcp-auth-setup.rs @@ -8,9 +8,9 @@ use clap::Parser; use colored::*; -use dialoguer::{theme::ColorfulTheme, Confirm, Input, Select}; +use dialoguer::{Confirm, Input, Select, theme::ColorfulTheme}; use pulseengine_mcp_auth::{ - config::StorageConfig, AuthConfig, AuthenticationManager, Role, ValidationConfig, + AuthConfig, AuthenticationManager, Role, ValidationConfig, config::StorageConfig, }; use std::path::PathBuf; use std::process; @@ -146,7 +146,10 @@ async fn run_setup(cli: Cli) -> Result<(), Box> { ); println!("{}", "─────────────────────────────────────────".yellow()); - std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", &master_key); + // SAFETY: Setting environment variable during initialization + unsafe { + std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", &master_key); + } let auth_config = AuthConfig { enabled: true, @@ -227,7 +230,7 @@ async fn run_setup(cli: Cli) -> Result<(), Box> { } fn generate_master_key() -> Result> { - use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine}; + use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD}; use rand::Rng; println!("Generating new master encryption key..."); diff --git a/mcp-auth/src/config.rs b/mcp-auth/src/config.rs index e2b6cd01..dedafaa6 100644 --- a/mcp-auth/src/config.rs +++ b/mcp-auth/src/config.rs @@ -227,8 +227,12 @@ mod tests { #[test] fn test_storage_config_file() { + let expected_path = std::env::temp_dir() + .join("mcp-auth-config-test") + .join("test_storage"); + let storage = StorageConfig::File { - path: PathBuf::from("/tmp/test"), + path: expected_path.clone(), file_permissions: 0o644, dir_permissions: 0o755, require_secure_filesystem: false, @@ -243,7 +247,7 @@ mod tests { require_secure_filesystem, enable_filesystem_monitoring, } => { - assert_eq!(path, PathBuf::from("/tmp/test")); + assert_eq!(path, expected_path); assert_eq!(file_permissions, 0o644); assert_eq!(dir_permissions, 0o755); assert!(!require_secure_filesystem); diff --git a/mcp-auth/src/consent.rs b/mcp-auth/src/consent.rs index 9c37d39d..cc637243 100644 --- a/mcp-auth/src/consent.rs +++ b/mcp-auth/src/consent.rs @@ -441,11 +441,15 @@ mod tests { record.add_data_category("personal_identifiers".to_string()); // Duplicate assert_eq!(record.data_categories.len(), 2); - assert!(record - .data_categories - .contains(&"personal_identifiers".to_string())); - assert!(record - .data_categories - .contains(&"authentication_data".to_string())); + assert!( + record + .data_categories + .contains(&"personal_identifiers".to_string()) + ); + assert!( + record + .data_categories + .contains(&"authentication_data".to_string()) + ); } } diff --git a/mcp-auth/src/crypto/encryption.rs b/mcp-auth/src/crypto/encryption.rs index cde2bc07..5ecb39e7 100644 --- a/mcp-auth/src/crypto/encryption.rs +++ b/mcp-auth/src/crypto/encryption.rs @@ -4,10 +4,10 @@ //! securely, inspired by Loxone's RSA/AES encryption approach. use aes_gcm::{ - aead::{Aead, AeadCore, KeyInit, OsRng}, Aes256Gcm, Key, Nonce, + aead::{Aead, AeadCore, KeyInit, OsRng}, }; -use base64::{engine::general_purpose::STANDARD as BASE64, Engine}; +use base64::{Engine, engine::general_purpose::STANDARD as BASE64}; use serde::{Deserialize, Serialize}; /// Encrypted data with nonce diff --git a/mcp-auth/src/crypto/hashing.rs b/mcp-auth/src/crypto/hashing.rs index b03f7941..27d68143 100644 --- a/mcp-auth/src/crypto/hashing.rs +++ b/mcp-auth/src/crypto/hashing.rs @@ -3,7 +3,7 @@ //! This module implements secure hashing using SHA256 HMAC and salt, //! following best practices from the Loxone MCP implementation. -use base64::{engine::general_purpose::STANDARD as BASE64, Engine}; +use base64::{Engine, engine::general_purpose::STANDARD as BASE64}; use rand::RngCore; use sha2::{Digest, Sha256}; use std::fmt; diff --git a/mcp-auth/src/crypto/keys.rs b/mcp-auth/src/crypto/keys.rs index c714977b..b1a45018 100644 --- a/mcp-auth/src/crypto/keys.rs +++ b/mcp-auth/src/crypto/keys.rs @@ -3,8 +3,8 @@ //! This module provides secure key generation similar to Loxone's //! approach, with URL-safe encoding and proper randomness. -use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine}; -use rand::{distributions::Alphanumeric, Rng, RngCore}; +use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD}; +use rand::{Rng, RngCore, distributions::Alphanumeric}; /// Key derivation errors #[derive(Debug, thiserror::Error)] diff --git a/mcp-auth/src/crypto/mod.rs b/mcp-auth/src/crypto/mod.rs index e47952f7..ff08f54e 100644 --- a/mcp-auth/src/crypto/mod.rs +++ b/mcp-auth/src/crypto/mod.rs @@ -7,9 +7,9 @@ pub mod encryption; pub mod hashing; pub mod keys; -pub use encryption::{decrypt_data, encrypt_data, EncryptionError}; -pub use hashing::{generate_salt, hash_api_key, verify_api_key, HashingError}; -pub use keys::{derive_key, generate_secure_key, KeyDerivationError}; +pub use encryption::{EncryptionError, decrypt_data, encrypt_data}; +pub use hashing::{HashingError, generate_salt, hash_api_key, verify_api_key}; +pub use keys::{KeyDerivationError, derive_key, generate_secure_key}; pub use encryption::EncryptedData; /// Re-export common types diff --git a/mcp-auth/src/jwt.rs b/mcp-auth/src/jwt.rs index a299c0f1..79116d15 100644 --- a/mcp-auth/src/jwt.rs +++ b/mcp-auth/src/jwt.rs @@ -5,7 +5,7 @@ use chrono::{Duration, Utc}; use jsonwebtoken::{ - decode, encode, Algorithm, DecodingKey, EncodingKey, Header, TokenData, Validation, + Algorithm, DecodingKey, EncodingKey, Header, TokenData, Validation, decode, encode, }; use serde::{Deserialize, Serialize}; use std::collections::HashSet; diff --git a/mcp-auth/src/lib.rs b/mcp-auth/src/lib.rs index c253d4eb..03eba5b4 100644 --- a/mcp-auth/src/lib.rs +++ b/mcp-auth/src/lib.rs @@ -315,9 +315,9 @@ pub use models::{ SecureApiKey, }; pub use monitoring::{ - create_default_alert_rules, AlertAction, AlertRule, AlertThreshold, MonitoringError, - SecurityAlert, SecurityDashboard, SecurityEvent, SecurityEventType, SecurityMetrics, - SecurityMonitor, SecurityMonitorConfig, SystemHealth, + AlertAction, AlertRule, AlertThreshold, MonitoringError, SecurityAlert, SecurityDashboard, + SecurityEvent, SecurityEventType, SecurityMetrics, SecurityMonitor, SecurityMonitorConfig, + SystemHealth, create_default_alert_rules, }; pub use performance::{PerformanceConfig, PerformanceResults, PerformanceTest, TestOperation}; pub use permissions::{ diff --git a/mcp-auth/src/manager.rs b/mcp-auth/src/manager.rs index 1ebf9cc1..50b6a71f 100644 --- a/mcp-auth/src/manager.rs +++ b/mcp-auth/src/manager.rs @@ -1,11 +1,11 @@ //! Authentication manager implementation use crate::{ - audit::{events, AuditConfig, AuditEvent, AuditEventType, AuditLogger, AuditSeverity}, + audit::{AuditConfig, AuditEvent, AuditEventType, AuditLogger, AuditSeverity, events}, config::AuthConfig, jwt::{JwtConfig, JwtManager, TokenPair}, models::*, - storage::{create_storage_backend, StorageBackend}, + storage::{StorageBackend, create_storage_backend}, }; use chrono::{DateTime, Utc}; use pulseengine_mcp_protocol::{Request, Response}; @@ -887,8 +887,10 @@ impl AuthenticationManager { crate::audit::AuditEventType::SystemStartup, crate::audit::AuditSeverity::Info, "role_rate_limiter".to_string(), - format!("Rate limit configuration update requested for role '{}' (max_requests: {}, window: {} min)", - role_key, config.max_requests_per_window, config.window_duration_minutes), + format!( + "Rate limit configuration update requested for role '{}' (max_requests: {}, window: {} min)", + role_key, config.max_requests_per_window, config.window_duration_minutes + ), ); let _ = self.audit_logger.log(audit_event).await; diff --git a/mcp-auth/src/manager_vault.rs b/mcp-auth/src/manager_vault.rs index 3dddd76b..82588e61 100644 --- a/mcp-auth/src/manager_vault.rs +++ b/mcp-auth/src/manager_vault.rs @@ -4,10 +4,10 @@ //! master keys and configuration from external vault systems like Infisical. use crate::{ + AuthConfig, AuthenticationManager, ValidationConfig, config::StorageConfig, manager::AuthError, vault::{VaultConfig, VaultError, VaultIntegration}, - AuthConfig, AuthenticationManager, ValidationConfig, }; use std::collections::HashMap; use tracing::{debug, info, warn}; @@ -38,7 +38,10 @@ impl VaultAuthenticationManager { } Err(e) => { if fallback_to_env { - warn!("Failed to connect to vault ({}), falling back to environment variables", e); + warn!( + "Failed to connect to vault ({}), falling back to environment variables", + e + ); None } else { return Err(VaultAuthManagerError::VaultError(e)); @@ -81,7 +84,10 @@ impl VaultAuthenticationManager { }; // Set master key in environment for this process - std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", &master_key); + // SAFETY: Setting environment variable in single-threaded context during initialization + unsafe { + std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", &master_key); + } // Try to get additional configuration from vault if let Some(vault) = &vault_integration { @@ -370,7 +376,9 @@ mod tests { let mut auth_config = AuthConfig { enabled: true, storage: StorageConfig::File { - path: "/tmp/test".into(), + path: std::env::temp_dir() + .join("mcp-auth-vault-test") + .join("test_vault"), file_permissions: 0o600, dir_permissions: 0o700, require_secure_filesystem: false, diff --git a/mcp-auth/src/middleware/mcp_auth.rs b/mcp-auth/src/middleware/mcp_auth.rs index d1c21048..6d1547a5 100644 --- a/mcp-auth/src/middleware/mcp_auth.rs +++ b/mcp-auth/src/middleware/mcp_auth.rs @@ -4,7 +4,7 @@ //! for MCP requests, integrating with the AuthenticationManager and //! permission system. -use crate::{models::Role, security::RequestSecurityValidator, AuthContext, AuthenticationManager}; +use crate::{AuthContext, AuthenticationManager, models::Role, security::RequestSecurityValidator}; use async_trait::async_trait; use pulseengine_mcp_protocol::{Error as McpError, Request, Response}; use std::collections::HashMap; diff --git a/mcp-auth/src/middleware/session_middleware.rs b/mcp-auth/src/middleware/session_middleware.rs index a567bf72..dbd2e777 100644 --- a/mcp-auth/src/middleware/session_middleware.rs +++ b/mcp-auth/src/middleware/session_middleware.rs @@ -4,11 +4,11 @@ //! JWT token validation, and enhanced security features. use crate::{ + AuthContext, AuthenticationManager, jwt::JwtError, middleware::mcp_auth::{AuthExtractionError, McpAuthConfig, McpRequestContext}, security::RequestSecurityValidator, session::{Session, SessionError, SessionManager}, - AuthContext, AuthenticationManager, }; use pulseengine_mcp_protocol::{Error as McpError, Request, Response}; use std::collections::HashMap; @@ -403,7 +403,7 @@ impl SessionMiddleware { Ok((auth_context, "Bearer".to_string())) } "Basic" => { - use base64::{engine::general_purpose, Engine as _}; + use base64::{Engine as _, engine::general_purpose}; let decoded = general_purpose::STANDARD.decode(parts[1]).map_err(|_| { SessionMiddlewareError::AuthError(AuthExtractionError::InvalidFormat( "Invalid Base64 in Basic auth".to_string(), @@ -554,8 +554,8 @@ impl SessionMiddleware { mod tests { use super::*; use crate::{ - session::{MemorySessionStorage, SessionConfig}, AuthConfig, + session::{MemorySessionStorage, SessionConfig}, }; async fn create_test_middleware() -> SessionMiddleware { diff --git a/mcp-auth/src/models.rs b/mcp-auth/src/models.rs index 10f68324..9194e777 100644 --- a/mcp-auth/src/models.rs +++ b/mcp-auth/src/models.rs @@ -105,7 +105,7 @@ impl ApiKey { ) -> Result { use crate::crypto::hashing::verify_api_key; - if let (Some(ref hash), Some(ref salt)) = (&self.secret_hash, &self.salt) { + if let (Some(hash), Some(salt)) = (&self.secret_hash, &self.salt) { verify_api_key(provided_key, hash, salt) } else { // Fallback to plain text comparison for legacy keys @@ -200,7 +200,7 @@ impl SecureApiKey { ) -> Result { use crate::crypto::hashing::verify_api_key; - if let (Some(ref hash), Some(ref salt)) = (&self.secret_hash, &self.salt) { + if let (Some(hash), Some(salt)) = (&self.secret_hash, &self.salt) { verify_api_key(provided_key, hash, salt) } else { // Can't verify without hash - this should not happen in production diff --git a/mcp-auth/src/monitoring/dashboard_server.rs b/mcp-auth/src/monitoring/dashboard_server.rs index 69ad251a..8f854e35 100644 --- a/mcp-auth/src/monitoring/dashboard_server.rs +++ b/mcp-auth/src/monitoring/dashboard_server.rs @@ -682,9 +682,11 @@ mod tests { let server = DashboardServer::with_default_config(monitor); // Test valid token - assert!(server - .authenticate_request(Some("dashboard-token-123")) - .is_ok()); + assert!( + server + .authenticate_request(Some("dashboard-token-123")) + .is_ok() + ); // Test invalid token assert!(server.authenticate_request(Some("invalid-token")).is_err()); @@ -693,17 +695,23 @@ mod tests { assert!(server.authenticate_request(None).is_err()); // Test Bearer token authentication - assert!(server - .authenticate_bearer_token(Some("Bearer dashboard-token-123")) - .is_ok()); - assert!(server - .authenticate_bearer_token(Some("Invalid format")) - .is_err()); + assert!( + server + .authenticate_bearer_token(Some("Bearer dashboard-token-123")) + .is_ok() + ); + assert!( + server + .authenticate_bearer_token(Some("Invalid format")) + .is_err() + ); // Test API key authentication - assert!(server - .authenticate_api_key(Some("dashboard-token-123")) - .is_ok()); + assert!( + server + .authenticate_api_key(Some("dashboard-token-123")) + .is_ok() + ); assert!(server.authenticate_api_key(Some("invalid-key")).is_err()); } diff --git a/mcp-auth/src/monitoring/mod.rs b/mcp-auth/src/monitoring/mod.rs index 7f964e2f..aa86bb03 100644 --- a/mcp-auth/src/monitoring/mod.rs +++ b/mcp-auth/src/monitoring/mod.rs @@ -7,9 +7,9 @@ pub mod dashboard_server; pub mod security_monitor; pub use security_monitor::{ - create_default_alert_rules, AlertAction, AlertRule, AlertThreshold, MonitoringError, - SecurityAlert, SecurityDashboard, SecurityEvent, SecurityEventType, SecurityMetrics, - SecurityMonitor, SecurityMonitorConfig, SystemHealth, + AlertAction, AlertRule, AlertThreshold, MonitoringError, SecurityAlert, SecurityDashboard, + SecurityEvent, SecurityEventType, SecurityMetrics, SecurityMonitor, SecurityMonitorConfig, + SystemHealth, create_default_alert_rules, }; #[cfg(test)] diff --git a/mcp-auth/src/monitoring/security_monitor.rs b/mcp-auth/src/monitoring/security_monitor.rs index 7f0f0ba1..127df095 100644 --- a/mcp-auth/src/monitoring/security_monitor.rs +++ b/mcp-auth/src/monitoring/security_monitor.rs @@ -4,9 +4,9 @@ //! real-time metrics, alerting, threat detection, and security dashboards. use crate::{ + AuthContext, security::{SecuritySeverity, SecurityViolation, SecurityViolationType}, session::Session, - AuthContext, }; use serde::{Deserialize, Serialize}; use std::collections::{HashMap, VecDeque}; diff --git a/mcp-auth/src/permissions/mcp_permissions.rs b/mcp-auth/src/permissions/mcp_permissions.rs index 1005dacd..cf3f940b 100644 --- a/mcp-auth/src/permissions/mcp_permissions.rs +++ b/mcp-auth/src/permissions/mcp_permissions.rs @@ -3,7 +3,7 @@ //! This module provides comprehensive permission management for MCP tools, //! resources, and custom operations with role-based access control. -use crate::{models::Role, AuthContext}; +use crate::{AuthContext, models::Role}; use serde::{Deserialize, Serialize}; use std::collections::{HashMap, HashSet}; use thiserror::Error; @@ -682,18 +682,22 @@ mod tests { .allow_role_resource(Role::Monitor, "system://status") .deny_role_resource(Role::Monitor, "loxone://admin/*"); - assert!(config - .tools - .tool_permissions - .get("control_device") - .unwrap() - .contains(&Role::Operator)); - assert!(config - .resources - .resource_permissions - .get("system://status") - .unwrap() - .contains(&Role::Monitor)); + assert!( + config + .tools + .tool_permissions + .get("control_device") + .unwrap() + .contains(&Role::Operator) + ); + assert!( + config + .resources + .resource_permissions + .get("system://status") + .unwrap() + .contains(&Role::Monitor) + ); assert_eq!(config.custom_rules.len(), 1); } } diff --git a/mcp-auth/src/session/mod.rs b/mcp-auth/src/session/mod.rs index ccccc300..f505ff57 100644 --- a/mcp-auth/src/session/mod.rs +++ b/mcp-auth/src/session/mod.rs @@ -13,8 +13,8 @@ pub use session_manager::{ #[cfg(test)] mod tests { use super::*; - use crate::models::Role; use crate::AuthContext; + use crate::models::Role; use std::sync::Arc; #[test] diff --git a/mcp-auth/src/session/session_manager.rs b/mcp-auth/src/session/session_manager.rs index 56e69bba..be91300c 100644 --- a/mcp-auth/src/session/session_manager.rs +++ b/mcp-auth/src/session/session_manager.rs @@ -4,8 +4,8 @@ //! session storage, lifecycle management, and security features. use crate::{ - jwt::{JwtConfig, JwtError, JwtManager}, AuthContext, + jwt::{JwtConfig, JwtError, JwtManager}, }; use serde::{Deserialize, Serialize}; use std::collections::HashMap; diff --git a/mcp-auth/src/setup/mod.rs b/mcp-auth/src/setup/mod.rs index d8dc69b6..d559142d 100644 --- a/mcp-auth/src/setup/mod.rs +++ b/mcp-auth/src/setup/mod.rs @@ -132,7 +132,10 @@ impl SetupBuilder { }; // Set master key in environment for this process - std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", &master_key); + // SAFETY: Setting environment variable during initialization + unsafe { + std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", &master_key); + } // Use storage config or default let storage_config = self @@ -245,7 +248,7 @@ Created: {} /// Generate a new master encryption key fn generate_master_key() -> Result { - use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine}; + use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD}; use rand::Rng; let mut key = [0u8; 32]; diff --git a/mcp-auth/src/storage.rs b/mcp-auth/src/storage.rs index 87129dab..f5f92a61 100644 --- a/mcp-auth/src/storage.rs +++ b/mcp-auth/src/storage.rs @@ -199,7 +199,7 @@ impl FileStorage { "nfs" | "nfs4" | "cifs" | "smb" | "smbfs" | "fuse.sshfs" => { return Err(StorageError::Permission(format!( - "Storage path {} is on insecure network filesystem: {}", + "Storage path {} is on insecure network filesystem: {}", path_str, fs_type ))); } @@ -636,7 +636,10 @@ impl StorageBackend for EnvironmentStorage { async fn save_all_keys(&self, keys: &HashMap) -> Result<(), StorageError> { let content = serde_json::to_string(keys)?; - std::env::set_var(&self.var_name, content); + // SAFETY: Setting environment variable for storage purposes + unsafe { + std::env::set_var(&self.var_name, content); + } debug!("Saved {} keys to environment storage", keys.len()); Ok(()) @@ -900,7 +903,10 @@ mod tests { let storage = EnvironmentStorage::new("TEST_MCP_KEYS".to_string()); // Clear any existing value - std::env::remove_var("TEST_MCP_KEYS"); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var("TEST_MCP_KEYS"); + } let keys = storage.load_keys().await.unwrap(); assert!(keys.is_empty()); @@ -909,7 +915,10 @@ mod tests { #[tokio::test] async fn test_environment_storage_save_and_load_key() { let var_name = "TEST_MCP_KEYS_SAVE_LOAD"; - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } let storage = EnvironmentStorage::new(var_name.to_string()); let test_key = create_test_key("env-test-key", Role::Monitor); @@ -924,13 +933,19 @@ mod tests { assert!(std::env::var(var_name).is_ok()); // Cleanup - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } } #[tokio::test] async fn test_environment_storage_multiple_keys() { let var_name = "TEST_MCP_KEYS_MULTIPLE"; - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } let storage = EnvironmentStorage::new(var_name.to_string()); let test_keys = create_test_keys(); @@ -946,13 +961,19 @@ mod tests { } // Cleanup - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } } #[tokio::test] async fn test_environment_storage_delete_key() { let var_name = "TEST_MCP_KEYS_DELETE"; - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } let storage = EnvironmentStorage::new(var_name.to_string()); let test_keys = create_test_keys(); @@ -968,26 +989,38 @@ mod tests { assert!(!remaining_keys.contains_key(&key_to_delete)); // Cleanup - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } } #[tokio::test] async fn test_environment_storage_empty_content() { let var_name = "TEST_MCP_KEYS_EMPTY"; - std::env::set_var(var_name, ""); + // SAFETY: Setting test environment variable + unsafe { + std::env::set_var(var_name, ""); + } let storage = EnvironmentStorage::new(var_name.to_string()); let keys = storage.load_keys().await.unwrap(); assert!(keys.is_empty()); // Cleanup - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } } #[tokio::test] async fn test_environment_storage_invalid_json() { let var_name = "TEST_MCP_KEYS_INVALID"; - std::env::set_var(var_name, "invalid json content"); + // SAFETY: Setting test environment variable + unsafe { + std::env::set_var(var_name, "invalid json content"); + } let storage = EnvironmentStorage::new(var_name.to_string()); let result = storage.load_keys().await; @@ -999,13 +1032,19 @@ mod tests { } // Cleanup - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } } #[tokio::test] async fn test_environment_storage_overwrite_existing() { let var_name = "TEST_MCP_KEYS_OVERWRITE"; - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } let storage = EnvironmentStorage::new(var_name.to_string()); @@ -1025,7 +1064,10 @@ mod tests { assert!(loaded_keys.contains_key(new_keys.keys().next().unwrap())); // Cleanup - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } } } @@ -1034,10 +1076,13 @@ mod tests { async fn create_test_file_storage() -> (FileStorage, TempDir) { // Set a consistent master key for all file storage tests - std::env::set_var( - "PULSEENGINE_MCP_MASTER_KEY", - "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", - ); + // SAFETY: Setting test environment variable + unsafe { + std::env::set_var( + "PULSEENGINE_MCP_MASTER_KEY", + "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", + ); + } let temp_dir = TempDir::new().unwrap(); let storage_path = temp_dir.path().join("test_keys.enc"); @@ -1181,10 +1226,13 @@ mod tests { // Store and set master key in thread-safe manner let original_master_key = std::env::var("PULSEENGINE_MCP_MASTER_KEY").ok(); - std::env::set_var( - "PULSEENGINE_MCP_MASTER_KEY", - "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", - ); + // SAFETY: Setting test environment variable + unsafe { + std::env::set_var( + "PULSEENGINE_MCP_MASTER_KEY", + "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", + ); + } // Small delay to ensure environment variable is set across threads tokio::time::sleep(std::time::Duration::from_millis(10)).await; @@ -1223,9 +1271,12 @@ mod tests { } // Restore original environment variable or remove if it didn't exist - match original_master_key { - Some(key) => std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", key), - None => std::env::remove_var("PULSEENGINE_MCP_MASTER_KEY"), + // SAFETY: Restoring test environment variable + unsafe { + match original_master_key { + Some(key) => std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", key), + None => std::env::remove_var("PULSEENGINE_MCP_MASTER_KEY"), + } } } @@ -1307,10 +1358,13 @@ mod tests { let original = std::env::var("PULSEENGINE_MCP_MASTER_KEY").ok(); // Set a consistent master key for cleanup testing - std::env::set_var( - "PULSEENGINE_MCP_MASTER_KEY", - "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", - ); + // SAFETY: Setting test environment variable + unsafe { + std::env::set_var( + "PULSEENGINE_MCP_MASTER_KEY", + "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", + ); + } original }; @@ -1353,9 +1407,12 @@ mod tests { assert_eq!(remaining_backups, 2); // Restore original environment variable or remove if it didn't exist - match original_master_key { - Some(key) => std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", key), - None => std::env::remove_var("PULSEENGINE_MCP_MASTER_KEY"), + // SAFETY: Restoring test environment variable + unsafe { + match original_master_key { + Some(key) => std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", key), + None => std::env::remove_var("PULSEENGINE_MCP_MASTER_KEY"), + } } } @@ -1394,10 +1451,13 @@ mod tests { let original = std::env::var("PULSEENGINE_MCP_MASTER_KEY").ok(); // Set a consistent master key for atomic operations testing - std::env::set_var( - "PULSEENGINE_MCP_MASTER_KEY", - "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", - ); + // SAFETY: Setting test environment variable + unsafe { + std::env::set_var( + "PULSEENGINE_MCP_MASTER_KEY", + "l9EYbalIRp2CF35M4mKcWDqRvx3TFc7U4nX5zvQF56Q", + ); + } original }; @@ -1463,9 +1523,12 @@ mod tests { } // Restore original environment variable or remove if it didn't exist - match original_master_key { - Some(key) => std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", key), - None => std::env::remove_var("PULSEENGINE_MCP_MASTER_KEY"), + // SAFETY: Restoring test environment variable + unsafe { + match original_master_key { + Some(key) => std::env::set_var("PULSEENGINE_MCP_MASTER_KEY", key), + None => std::env::remove_var("PULSEENGINE_MCP_MASTER_KEY"), + } } } } @@ -1491,7 +1554,10 @@ mod tests { #[tokio::test] async fn test_create_environment_storage_backend() { let var_name = "TEST_FACTORY_ENV_STORAGE"; - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } let config = StorageConfig::Environment { prefix: var_name.to_string(), @@ -1507,7 +1573,10 @@ mod tests { assert!(keys.contains_key(&test_key.id)); // Cleanup - std::env::remove_var(var_name); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var(var_name); + } } #[tokio::test] @@ -1592,7 +1661,10 @@ mod tests { } // Cleanup - std::env::remove_var("TEST_TRAIT_OBJECT"); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var("TEST_TRAIT_OBJECT"); + } } #[tokio::test] diff --git a/mcp-auth/src/transport/http_auth.rs b/mcp-auth/src/transport/http_auth.rs index 78ba8eb5..3e73d402 100644 --- a/mcp-auth/src/transport/http_auth.rs +++ b/mcp-auth/src/transport/http_auth.rs @@ -149,20 +149,20 @@ impl HttpAuthExtractor { } let encoded = &auth_header[6..]; // Skip "Basic " - use base64::{engine::general_purpose, Engine as _}; + use base64::{Engine as _, engine::general_purpose}; let decoded = match general_purpose::STANDARD.decode(encoded) { Ok(bytes) => match String::from_utf8(bytes) { Ok(string) => string, Err(_) => { return Err(TransportAuthError::InvalidFormat( "Invalid UTF-8 in Basic auth".to_string(), - )) + )); } }, Err(_) => { return Err(TransportAuthError::InvalidFormat( "Invalid Base64 in Basic auth".to_string(), - )) + )); } }; @@ -423,7 +423,7 @@ mod tests { }); let api_key = "lmcp_test_1234567890abcdef"; - use base64::{engine::general_purpose, Engine as _}; + use base64::{Engine as _, engine::general_purpose}; let encoded = general_purpose::STANDARD.encode(format!("{}:", api_key)); let mut headers = HashMap::new(); headers.insert("Authorization".to_string(), format!("Basic {}", encoded)); diff --git a/mcp-auth/src/transport/stdio_auth.rs b/mcp-auth/src/transport/stdio_auth.rs index 7d888da3..05b3450a 100644 --- a/mcp-auth/src/transport/stdio_auth.rs +++ b/mcp-auth/src/transport/stdio_auth.rs @@ -320,7 +320,10 @@ mod tests { #[test] fn test_environment_variable_extraction() { - std::env::set_var("TEST_MCP_API_KEY", "lmcp_test_1234567890abcdef"); + // SAFETY: Setting test environment variable + unsafe { + std::env::set_var("TEST_MCP_API_KEY", "lmcp_test_1234567890abcdef"); + } let config = StdioAuthConfig { api_key_env_var: "TEST_MCP_API_KEY".to_string(), @@ -337,7 +340,10 @@ mod tests { assert_eq!(context.method, "Environment"); assert_eq!(context.transport_type, TransportType::Stdio); - std::env::remove_var("TEST_MCP_API_KEY"); + // SAFETY: Removing test environment variable + unsafe { + std::env::remove_var("TEST_MCP_API_KEY"); + } } #[test] diff --git a/mcp-auth/src/transport/websocket_auth.rs b/mcp-auth/src/transport/websocket_auth.rs index 3cf76a1c..75163b13 100644 --- a/mcp-auth/src/transport/websocket_auth.rs +++ b/mcp-auth/src/transport/websocket_auth.rs @@ -362,7 +362,9 @@ impl AuthExtractor for WebSocketAuthExtractor { // Warn about insecure authentication methods if context.method == "QueryParams" { - tracing::warn!("WebSocket authentication via query parameters is less secure - consider using headers"); + tracing::warn!( + "WebSocket authentication via query parameters is less secure - consider using headers" + ); } Ok(()) diff --git a/mcp-auth/tests/test_utils.rs b/mcp-auth/tests/test_utils.rs index 1439877f..68c07e78 100644 --- a/mcp-auth/tests/test_utils.rs +++ b/mcp-auth/tests/test_utils.rs @@ -7,10 +7,10 @@ use async_trait::async_trait; use chrono::{Duration, Utc}; use pulseengine_mcp_auth::{ + AuthenticationManager, config::{AuthConfig, StorageConfig}, models::{ApiKey, AuthContext, Role}, storage::{StorageBackend, StorageError}, - AuthenticationManager, }; use std::collections::HashMap; use std::sync::{Arc, Mutex}; @@ -131,7 +131,9 @@ impl TestDataGenerator { pub fn file_storage_config() -> AuthConfig { let mut config = Self::test_config(); config.storage = StorageConfig::File { - path: std::env::temp_dir().join("mcp-auth-test").join("keys.enc"), + path: std::env::temp_dir() + .join(format!("mcp-auth-test-{}", uuid::Uuid::new_v4())) + .join("keys.enc"), file_permissions: 0o600, dir_permissions: 0o700, require_secure_filesystem: false, diff --git a/mcp-auth/tests/vault_integration_tests.rs b/mcp-auth/tests/vault_integration_tests.rs index 4acee1ac..bd9d0936 100644 --- a/mcp-auth/tests/vault_integration_tests.rs +++ b/mcp-auth/tests/vault_integration_tests.rs @@ -71,10 +71,13 @@ mod vault_tests { // We can't actually set them in tests without affecting the test environment // Clear any existing variables for this test - env::remove_var("INFISICAL_UNIVERSAL_AUTH_CLIENT_ID"); - env::remove_var("INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET"); - env::remove_var("INFISICAL_PROJECT_ID"); - env::remove_var("INFISICAL_SECRET_PATH"); + // SAFETY: Removing test environment variables + unsafe { + env::remove_var("INFISICAL_UNIVERSAL_AUTH_CLIENT_ID"); + env::remove_var("INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET"); + env::remove_var("INFISICAL_PROJECT_ID"); + env::remove_var("INFISICAL_SECRET_PATH"); + } // Test that missing credentials are handled assert!(env::var("INFISICAL_UNIVERSAL_AUTH_CLIENT_ID").is_err()); @@ -91,7 +94,7 @@ mod vault_tests { #[cfg(all(test, feature = "integration-tests"))] mod integration_tests { use super::*; - use pulseengine_mcp_auth::vault::{create_vault_client, VaultIntegration}; + use pulseengine_mcp_auth::vault::{VaultIntegration, create_vault_client}; // Helper to check if integration test environment is available fn integration_env_available() -> bool { diff --git a/mcp-cli-derive/src/lib.rs b/mcp-cli-derive/src/lib.rs index b48d8d68..46002452 100644 --- a/mcp-cli-derive/src/lib.rs +++ b/mcp-cli-derive/src/lib.rs @@ -5,7 +5,7 @@ use proc_macro::TokenStream; use quote::quote; -use syn::{parse_macro_input, Attribute, Data, DeriveInput, Fields}; +use syn::{Attribute, Data, DeriveInput, Fields, parse_macro_input}; /// Derive macro for `McpConfig` /// @@ -98,14 +98,14 @@ fn generate_mcp_config_impl(input: &DeriveInput) -> syn::Result { return Err(syn::Error::new_spanned( input, "McpConfig can only be derived for structs", - )) + )); } }; @@ -187,14 +187,14 @@ fn generate_mcp_backend_impl(input: &DeriveInput) -> syn::Result { return Err(syn::Error::new_spanned( input, "McpBackend can only be derived for structs", - )) + )); } }; diff --git a/mcp-cli-derive/tests/test_mcp_config.rs b/mcp-cli-derive/tests/test_mcp_config.rs index a83abafa..f2a82531 100644 --- a/mcp-cli-derive/tests/test_mcp_config.rs +++ b/mcp-cli-derive/tests/test_mcp_config.rs @@ -391,8 +391,11 @@ mod integration_tests { } // Set environment variables - env::set_var("TEST_PORT", "9000"); - env::set_var("TEST_API_KEY", "secret-key"); + // SAFETY: Setting test environment variables + unsafe { + env::set_var("TEST_PORT", "9000"); + env::set_var("TEST_API_KEY", "secret-key"); + } // Parse without command line args let config = EnvConfig::try_parse_from(["test"]).expect("Failed to parse from env"); @@ -401,8 +404,11 @@ mod integration_tests { assert_eq!(config.api_key, Some("secret-key".to_string())); // Clean up - env::remove_var("TEST_PORT"); - env::remove_var("TEST_API_KEY"); + // SAFETY: Removing test environment variables + unsafe { + env::remove_var("TEST_PORT"); + env::remove_var("TEST_API_KEY"); + } } } diff --git a/mcp-cli/src/config.rs b/mcp-cli/src/config.rs index be7c0e46..76f8f57c 100644 --- a/mcp-cli/src/config.rs +++ b/mcp-cli/src/config.rs @@ -48,7 +48,7 @@ impl Default for DefaultLoggingConfig { impl DefaultLoggingConfig { pub fn initialize(&self) -> Result<(), CliError> { // Initialize tracing subscriber based on configuration - use tracing_subscriber::{fmt, prelude::*, EnvFilter}; + use tracing_subscriber::{EnvFilter, fmt, prelude::*}; let level = env::var("RUST_LOG").unwrap_or_else(|_| self.level.clone()); let filter = EnvFilter::try_from_default_env() diff --git a/mcp-cli/src/config_tests.rs b/mcp-cli/src/config_tests.rs index 86cf8e58..8168be11 100644 --- a/mcp-cli/src/config_tests.rs +++ b/mcp-cli/src/config_tests.rs @@ -1,7 +1,7 @@ //! Tests for configuration management and utilities -use crate::config::*; use crate::CliError; +use crate::config::*; use std::env; #[test] @@ -40,9 +40,11 @@ fn test_log_output_serialization() { assert_eq!(serde_json::to_string(&stdout_output).unwrap(), "\"stdout\""); assert_eq!(serde_json::to_string(&stderr_output).unwrap(), "\"stderr\""); - assert!(serde_json::to_string(&file_output) - .unwrap() - .contains("/path/to/log")); + assert!( + serde_json::to_string(&file_output) + .unwrap() + .contains("/path/to/log") + ); } #[test] @@ -52,7 +54,12 @@ fn test_logging_config_serialization() { let config = DefaultLoggingConfig { level: "debug".to_string(), format: LogFormat::Json, - output: LogOutput::File("/tmp/test.log".to_string()), + output: LogOutput::File( + std::env::temp_dir() + .join("mcp-cli-config-test.log") + .to_string_lossy() + .to_string(), + ), structured: false, }; @@ -144,13 +151,19 @@ fn test_env_utils_with_set_env_var() { use env_utils::*; // Set a temporary env var for testing - env::set_var("TEST_VAR_PORT", "9090"); + // SAFETY: Setting test environment variable + unsafe { + env::set_var("TEST_VAR_PORT", "9090"); + } let result: u16 = get_env_or_default("TEST_VAR_PORT", 8080); assert_eq!(result, 9090); // Clean up - env::remove_var("TEST_VAR_PORT"); + // SAFETY: Removing test environment variable + unsafe { + env::remove_var("TEST_VAR_PORT"); + } } #[test] @@ -161,9 +174,11 @@ fn test_env_utils_get_required_env_missing() { assert!(result.is_err()); let error = result.unwrap_err(); - assert!(error - .to_string() - .contains("Missing required environment variable")); + assert!( + error + .to_string() + .contains("Missing required environment variable") + ); assert!(error.to_string().contains("DEFINITELY_MISSING_VAR_12345")); } @@ -172,14 +187,20 @@ fn test_env_utils_get_required_env_present() { use env_utils::*; // Set a temporary env var - env::set_var("TEST_REQUIRED_VAR", "test_value"); + // SAFETY: Setting test environment variable + unsafe { + env::set_var("TEST_REQUIRED_VAR", "test_value"); + } let result: Result = get_required_env("TEST_REQUIRED_VAR"); assert!(result.is_ok()); assert_eq!(result.unwrap(), "test_value"); // Clean up - env::remove_var("TEST_REQUIRED_VAR"); + // SAFETY: Removing test environment variable + unsafe { + env::remove_var("TEST_REQUIRED_VAR"); + } } #[test] @@ -187,18 +208,26 @@ fn test_env_utils_get_required_env_invalid_type() { use env_utils::*; // Set env var with invalid number format - env::set_var("TEST_INVALID_NUMBER", "not_a_number"); + // SAFETY: Setting test environment variable + unsafe { + env::set_var("TEST_INVALID_NUMBER", "not_a_number"); + } let result: Result = get_required_env("TEST_INVALID_NUMBER"); assert!(result.is_err()); let error = result.unwrap_err(); - assert!(error - .to_string() - .contains("Invalid value for TEST_INVALID_NUMBER")); + assert!( + error + .to_string() + .contains("Invalid value for TEST_INVALID_NUMBER") + ); // Clean up - env::remove_var("TEST_INVALID_NUMBER"); + // SAFETY: Removing test environment variable + unsafe { + env::remove_var("TEST_INVALID_NUMBER"); + } } #[test] @@ -206,14 +235,20 @@ fn test_env_utils_get_required_env_valid_type() { use env_utils::*; // Set env var with valid number - env::set_var("TEST_VALID_NUMBER", "42"); + // SAFETY: Setting test environment variable + unsafe { + env::set_var("TEST_VALID_NUMBER", "42"); + } let result: Result = get_required_env("TEST_VALID_NUMBER"); assert!(result.is_ok()); assert_eq!(result.unwrap(), 42); // Clean up - env::remove_var("TEST_VALID_NUMBER"); + // SAFETY: Removing test environment variable + unsafe { + env::remove_var("TEST_VALID_NUMBER"); + } } #[test] diff --git a/mcp-cli/src/lib_tests.rs b/mcp-cli/src/lib_tests.rs index 7becf6b7..9a545bdf 100644 --- a/mcp-cli/src/lib_tests.rs +++ b/mcp-cli/src/lib_tests.rs @@ -6,24 +6,32 @@ use pulseengine_mcp_protocol::{Implementation, ProtocolVersion, ServerCapabiliti #[test] fn test_cli_error_creation() { let config_err = CliError::configuration("Config test"); - assert!(config_err - .to_string() - .contains("Configuration error: Config test")); + assert!( + config_err + .to_string() + .contains("Configuration error: Config test") + ); let parsing_err = CliError::parsing("Parse test"); - assert!(parsing_err - .to_string() - .contains("CLI parsing error: Parse test")); + assert!( + parsing_err + .to_string() + .contains("CLI parsing error: Parse test") + ); let setup_err = CliError::server_setup("Setup test"); - assert!(setup_err - .to_string() - .contains("Server setup error: Setup test")); + assert!( + setup_err + .to_string() + .contains("Server setup error: Setup test") + ); let logging_err = CliError::logging("Log test"); - assert!(logging_err - .to_string() - .contains("Logging setup error: Log test")); + assert!( + logging_err + .to_string() + .contains("Logging setup error: Log test") + ); } #[test] @@ -121,10 +129,12 @@ fn test_mcp_configuration_validation_failure() { // Test validation failure let result = config.validate(); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Validation failed")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Validation failed") + ); } #[test] diff --git a/mcp-cli/src/server.rs b/mcp-cli/src/server.rs index 4beb4ceb..278b9728 100644 --- a/mcp-cli/src/server.rs +++ b/mcp-cli/src/server.rs @@ -432,9 +432,10 @@ mod tests { .allow_method("PATCH"); assert!(cors.allowed_origins.contains(&"*".to_string())); - assert!(cors - .allowed_origins - .contains(&"https://example.com".to_string())); + assert!( + cors.allowed_origins + .contains(&"https://example.com".to_string()) + ); assert!(cors.allowed_methods.contains(&"PATCH".to_string())); } diff --git a/mcp-cli/src/utils_tests.rs b/mcp-cli/src/utils_tests.rs index 5884d1b9..7e42daa6 100644 --- a/mcp-cli/src/utils_tests.rs +++ b/mcp-cli/src/utils_tests.rs @@ -1,7 +1,7 @@ //! Comprehensive tests for utility functions -use crate::utils::*; use crate::CliError; +use crate::utils::*; use std::fs; use std::path::Path; use tempfile::TempDir; diff --git a/mcp-cli/tests/integration.rs b/mcp-cli/tests/integration.rs index 19acf30a..6ad8b61c 100644 --- a/mcp-cli/tests/integration.rs +++ b/mcp-cli/tests/integration.rs @@ -2,8 +2,8 @@ use clap::Parser; use pulseengine_mcp_cli::{ - server_builder, AuthMiddleware, CorsPolicy, DefaultLoggingConfig, LogFormat, LogOutput, - McpConfig, McpConfiguration, RateLimitMiddleware, TransportType, + AuthMiddleware, CorsPolicy, DefaultLoggingConfig, LogFormat, LogOutput, McpConfig, + McpConfiguration, RateLimitMiddleware, TransportType, server_builder, }; use pulseengine_mcp_protocol::ServerInfo; use std::time::Duration; @@ -259,9 +259,10 @@ fn test_advanced_server_configuration() { assert!(config.cors_policy.is_some()); let cors = config.cors_policy.as_ref().unwrap(); - assert!(cors - .allowed_origins - .contains(&"https://trusted.com".to_string())); + assert!( + cors.allowed_origins + .contains(&"https://trusted.com".to_string()) + ); assert_eq!(config.middleware.len(), 2); assert_eq!(config.custom_endpoints.len(), 2); diff --git a/mcp-external-validation/examples/fuzzing_demo.rs b/mcp-external-validation/examples/fuzzing_demo.rs index 1c5f8400..dbfdfe3c 100644 --- a/mcp-external-validation/examples/fuzzing_demo.rs +++ b/mcp-external-validation/examples/fuzzing_demo.rs @@ -4,7 +4,7 @@ //! an MCP server's robustness against malformed inputs. use pulseengine_mcp_external_validation::{ - fuzzing::fuzz_results_to_issues, FuzzTarget, McpFuzzer, ValidationConfig, + FuzzTarget, McpFuzzer, ValidationConfig, fuzzing::fuzz_results_to_issues, }; #[tokio::main] diff --git a/mcp-external-validation/examples/python_compatibility.rs b/mcp-external-validation/examples/python_compatibility.rs index 76580033..9bdcbc6f 100644 --- a/mcp-external-validation/examples/python_compatibility.rs +++ b/mcp-external-validation/examples/python_compatibility.rs @@ -1,6 +1,6 @@ //! Example of Python SDK compatibility testing -use pulseengine_mcp_external_validation::{python_sdk::PythonSdkTester, ValidationConfig}; +use pulseengine_mcp_external_validation::{ValidationConfig, python_sdk::PythonSdkTester}; #[tokio::main] async fn main() -> Result<(), Box> { diff --git a/mcp-external-validation/src/auth_integration.rs b/mcp-external-validation/src/auth_integration.rs index 282f6d38..8dc304a3 100644 --- a/mcp-external-validation/src/auth_integration.rs +++ b/mcp-external-validation/src/auth_integration.rs @@ -5,16 +5,16 @@ //! validation and security testing. use crate::{ - report::{IssueSeverity, TestScore, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, TestScore, ValidationIssue}, }; use pulseengine_mcp_auth::{ - validation::permissions, AuthenticationManager, RateLimitStats, Role, - ValidationConfig as AuthValidationConfig, + AuthenticationManager, RateLimitStats, Role, ValidationConfig as AuthValidationConfig, + validation::permissions, }; use reqwest::Client; use serde::{Deserialize, Serialize}; -use serde_json::{json, Value}; +use serde_json::{Value, json}; use std::collections::HashMap; use std::time::Duration; use tracing::{error, info, warn}; @@ -148,7 +148,7 @@ impl AuthIntegrationTester { /// Initialize authentication manager for testing pub async fn initialize_auth_manager(&mut self) -> ValidationResult<()> { - use pulseengine_mcp_auth::{config::StorageConfig, AuthConfig}; + use pulseengine_mcp_auth::{AuthConfig, config::StorageConfig}; // Create temporary in-memory authentication configuration for testing let auth_config = AuthConfig { diff --git a/mcp-external-validation/src/bin/mcp-compliance-report.rs b/mcp-external-validation/src/bin/mcp-compliance-report.rs index c2215495..96be5539 100644 --- a/mcp-external-validation/src/bin/mcp-compliance-report.rs +++ b/mcp-external-validation/src/bin/mcp-compliance-report.rs @@ -4,7 +4,7 @@ use clap::Parser; use pulseengine_mcp_external_validation::{ExternalValidator, ValidationConfig}; use std::fs; use std::process; -use tracing::{error, info, Level}; +use tracing::{Level, error, info}; #[derive(Parser)] #[command(name = "mcp-compliance-report")] diff --git a/mcp-external-validation/src/bin/mcp-validate.rs b/mcp-external-validation/src/bin/mcp-validate.rs index 9a2a883d..51524d53 100644 --- a/mcp-external-validation/src/bin/mcp-validate.rs +++ b/mcp-external-validation/src/bin/mcp-validate.rs @@ -3,7 +3,7 @@ use clap::Parser; use pulseengine_mcp_external_validation::{ExternalValidator, ValidationConfig}; use std::process; -use tracing::{error, info, warn, Level}; +use tracing::{Level, error, info, warn}; #[derive(Parser)] #[command(name = "mcp-validate")] @@ -203,11 +203,7 @@ async fn run_quick_validation(validator: &ExternalValidator, cli: &Cli) -> i32 { match status { pulseengine_mcp_external_validation::report::ComplianceStatus::Compliant => 0, pulseengine_mcp_external_validation::report::ComplianceStatus::Warning => { - if cli.strict { - 1 - } else { - 0 - } + if cli.strict { 1 } else { 0 } } _ => 1, } diff --git a/mcp-external-validation/src/config.rs b/mcp-external-validation/src/config.rs index d5ee5212..38474ff9 100644 --- a/mcp-external-validation/src/config.rs +++ b/mcp-external-validation/src/config.rs @@ -5,7 +5,7 @@ use std::collections::HashMap; use std::path::PathBuf; use std::time::Duration; -use crate::{ValidationError, ValidationResult, DEFAULT_RETRIES, DEFAULT_TIMEOUT_SECONDS}; +use crate::{DEFAULT_RETRIES, DEFAULT_TIMEOUT_SECONDS, ValidationError, ValidationResult}; /// Configuration for external validation #[derive(Debug, Clone, Serialize, Deserialize)] diff --git a/mcp-external-validation/src/cross_language.rs b/mcp-external-validation/src/cross_language.rs index ac480000..176fb8c0 100644 --- a/mcp-external-validation/src/cross_language.rs +++ b/mcp-external-validation/src/cross_language.rs @@ -5,8 +5,8 @@ //! true protocol interoperability. use crate::{ - report::{IssueSeverity, TestScore, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, TestScore, ValidationIssue}, }; use serde::{Deserialize, Serialize}; use serde_json::Value; diff --git a/mcp-external-validation/src/ecosystem.rs b/mcp-external-validation/src/ecosystem.rs index f67ec80a..a5d41350 100644 --- a/mcp-external-validation/src/ecosystem.rs +++ b/mcp-external-validation/src/ecosystem.rs @@ -5,8 +5,8 @@ //! compatibility beyond protocol compliance. use crate::{ - report::{IssueSeverity, TestScore, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, TestScore, ValidationIssue}, }; use reqwest::Client; use serde::{Deserialize, Serialize}; diff --git a/mcp-external-validation/src/fuzzing.rs b/mcp-external-validation/src/fuzzing.rs index f62dfe25..636449f4 100644 --- a/mcp-external-validation/src/fuzzing.rs +++ b/mcp-external-validation/src/fuzzing.rs @@ -4,11 +4,11 @@ //! against malformed, unexpected, or malicious inputs. use crate::{ - report::{IssueSeverity, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, ValidationIssue}, }; use arbitrary::{Arbitrary, Unstructured}; -use serde_json::{json, Value}; +use serde_json::{Value, json}; use std::time::{Duration, Instant}; use tracing::{debug, info}; diff --git a/mcp-external-validation/src/inspector.rs b/mcp-external-validation/src/inspector.rs index f2086a58..72d2dc12 100644 --- a/mcp-external-validation/src/inspector.rs +++ b/mcp-external-validation/src/inspector.rs @@ -4,8 +4,8 @@ //! (@modelcontextprotocol/inspector) for automated testing and validation of MCP servers. use crate::{ - report::{InspectorResult, IssueSeverity, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{InspectorResult, IssueSeverity, ValidationIssue}, }; use serde::Deserialize; use std::path::PathBuf; diff --git a/mcp-external-validation/src/jsonrpc.rs b/mcp-external-validation/src/jsonrpc.rs index 6ae56ef6..2924524d 100644 --- a/mcp-external-validation/src/jsonrpc.rs +++ b/mcp-external-validation/src/jsonrpc.rs @@ -4,13 +4,13 @@ //! using external validators and schema validation. use crate::{ - report::{IssueSeverity, JsonRpcValidatorResult, TestScore, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, JsonRpcValidatorResult, TestScore, ValidationIssue}, }; use jsonschema::{Draft, JSONSchema}; // Note: reqwest::Client used for real message collection use serde::{Deserialize, Serialize}; -use serde_json::{json, Value}; +use serde_json::{Value, json}; // use std::collections::HashMap; // Removed unused import use tokio::io::AsyncWriteExt; use tracing::{debug, info, warn}; @@ -1383,9 +1383,11 @@ mod tests { let issues = validator.validate_single_message(&invalid_request).unwrap(); assert!(!issues.is_empty()); - assert!(issues - .iter() - .any(|i| i.description.contains("Invalid JSON-RPC version"))); + assert!( + issues + .iter() + .any(|i| i.description.contains("Invalid JSON-RPC version")) + ); } #[test] diff --git a/mcp-external-validation/src/mcp_semantic.rs b/mcp-external-validation/src/mcp_semantic.rs index 8da8decb..992e1013 100644 --- a/mcp-external-validation/src/mcp_semantic.rs +++ b/mcp-external-validation/src/mcp_semantic.rs @@ -5,8 +5,8 @@ //! transitions, and protocol compliance. use crate::{ - report::{IssueSeverity, TestScore, ValidationIssue}, ValidationConfig, ValidationResult, + report::{IssueSeverity, TestScore, ValidationIssue}, }; use serde::{Deserialize, Serialize}; use serde_json::Value; @@ -1079,10 +1079,12 @@ mod tests { .validate_protocol_semantics(&messages) .await .unwrap(); - assert!(result - .issues - .iter() - .any(|i| i.description.contains("Unsupported protocol version"))); + assert!( + result + .issues + .iter() + .any(|i| i.description.contains("Unsupported protocol version")) + ); } #[tokio::test] @@ -1111,9 +1113,11 @@ mod tests { .validate_protocol_semantics(&messages) .await .unwrap(); - assert!(result - .issues - .iter() - .any(|i| i.description.contains("called before initialization"))); + assert!( + result + .issues + .iter() + .any(|i| i.description.contains("called before initialization")) + ); } } diff --git a/mcp-external-validation/src/mcp_validator.rs b/mcp-external-validation/src/mcp_validator.rs index 60a6cd7e..06ad691b 100644 --- a/mcp-external-validation/src/mcp_validator.rs +++ b/mcp-external-validation/src/mcp_validator.rs @@ -4,8 +4,8 @@ //! (Janix-ai/mcp-protocol-validator) to ensure compliance with MCP specifications. use crate::{ - report::{IssueSeverity, McpValidatorResult, TestScore, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, McpValidatorResult, TestScore, ValidationIssue}, }; use reqwest::Client; use serde::{Deserialize, Serialize}; diff --git a/mcp-external-validation/src/proptest.rs b/mcp-external-validation/src/proptest.rs index 70693cb7..23747150 100644 --- a/mcp-external-validation/src/proptest.rs +++ b/mcp-external-validation/src/proptest.rs @@ -12,12 +12,12 @@ use proptest::{collection, option}; #[cfg(feature = "proptest")] use proptest_derive::Arbitrary; #[cfg(feature = "proptest")] -use serde_json::{json, Value}; +use serde_json::{Value, json}; #[cfg(feature = "proptest")] use std::collections::HashMap; #[cfg(feature = "proptest")] -use crate::{jsonrpc::JsonRpcValidator, ValidationConfig, ValidationResult}; +use crate::{ValidationConfig, ValidationResult, jsonrpc::JsonRpcValidator}; /// Property-based test runner for MCP protocol compliance #[cfg(feature = "proptest")] diff --git a/mcp-external-validation/src/python_sdk.rs b/mcp-external-validation/src/python_sdk.rs index 96153a2d..b658bbe8 100644 --- a/mcp-external-validation/src/python_sdk.rs +++ b/mcp-external-validation/src/python_sdk.rs @@ -4,8 +4,8 @@ //! to ensure cross-framework interoperability. use crate::{ - report::{IssueSeverity, PythonSdkResult, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, PythonSdkResult, ValidationIssue}, }; use serde::{Deserialize, Serialize}; use std::fs; diff --git a/mcp-external-validation/src/security.rs b/mcp-external-validation/src/security.rs index 2e2b67a0..44a0372e 100644 --- a/mcp-external-validation/src/security.rs +++ b/mcp-external-validation/src/security.rs @@ -5,15 +5,15 @@ //! vulnerability scanning. use crate::{ - report::{IssueSeverity, TestScore, ValidationIssue}, ValidationConfig, ValidationError, ValidationResult, + report::{IssueSeverity, TestScore, ValidationIssue}, }; use reqwest::{ - header::{HeaderMap, HeaderValue, AUTHORIZATION}, Client, + header::{AUTHORIZATION, HeaderMap, HeaderValue}, }; use serde::{Deserialize, Serialize}; -use serde_json::{json, Value}; +use serde_json::{Value, json}; use std::collections::HashMap; use std::time::Duration; use tokio::time::timeout; @@ -554,7 +554,9 @@ impl SecurityTester { // Check if authentication is actually enforced if response.status().is_success() { // Server allows access without auth - likely disabled due to framework issue - warn!("Server accepts requests without authentication - likely disabled due to framework limitations"); + warn!( + "Server accepts requests without authentication - likely disabled due to framework limitations" + ); return Ok(false); } diff --git a/mcp-external-validation/src/validator.rs b/mcp-external-validation/src/validator.rs index 1bb9ac7f..a5fdaac1 100644 --- a/mcp-external-validation/src/validator.rs +++ b/mcp-external-validation/src/validator.rs @@ -1,6 +1,7 @@ //! Main external validator that orchestrates all validation components use crate::{ + ValidationError, ValidationResult, auth_integration::AuthIntegrationTester, config::ValidationConfig, cross_language::CrossLanguageTester, @@ -11,7 +12,6 @@ use crate::{ mcp_validator::McpValidatorClient, report::{ComplianceReport, ComplianceStatus, ExternalValidatorResults, PythonCompatResult}, security::SecurityTester, - ValidationError, ValidationResult, }; use std::time::{Duration, Instant}; use tracing::{error, info, warn}; diff --git a/mcp-logging/src/aggregation.rs b/mcp-logging/src/aggregation.rs index b7d7535d..ccd49cf4 100644 --- a/mcp-logging/src/aggregation.rs +++ b/mcp-logging/src/aggregation.rs @@ -13,7 +13,7 @@ use serde::{Deserialize, Serialize}; use std::collections::{HashMap, VecDeque}; use std::sync::Arc; use std::time::Duration; -use tokio::sync::{mpsc, RwLock}; +use tokio::sync::{RwLock, mpsc}; use tracing::{error, info}; use uuid::Uuid; diff --git a/mcp-logging/src/alerting.rs b/mcp-logging/src/alerting.rs index 00628940..f259b99b 100644 --- a/mcp-logging/src/alerting.rs +++ b/mcp-logging/src/alerting.rs @@ -13,7 +13,7 @@ use serde::{Deserialize, Serialize}; use std::collections::{HashMap, HashSet}; use std::sync::Arc; use std::time::Duration; -use tokio::sync::{mpsc, RwLock}; +use tokio::sync::{RwLock, mpsc}; use tracing::{error, info, warn}; use uuid::Uuid; diff --git a/mcp-logging/src/lib.rs b/mcp-logging/src/lib.rs index 4a59a879..f4871328 100644 --- a/mcp-logging/src/lib.rs +++ b/mcp-logging/src/lib.rs @@ -54,8 +54,8 @@ pub use dashboard::{ DataPoint, DataSource, GridPosition, LineStyle, Threshold, }; pub use metrics::{ - get_metrics, BusinessMetrics, ErrorMetrics, ErrorRecord, HealthMetrics, MetricsCollector, - MetricsSnapshot, RequestMetrics, + BusinessMetrics, ErrorMetrics, ErrorRecord, HealthMetrics, MetricsCollector, MetricsSnapshot, + RequestMetrics, get_metrics, }; pub use persistence::{MetricsPersistence, PersistedMetrics, PersistenceConfig, RotationInterval}; pub use profiling::{ @@ -67,8 +67,8 @@ pub use profiling::{ pub use sanitization::{LogSanitizer, SanitizationConfig}; pub use structured::{ErrorClass, StructuredContext, StructuredLogger}; pub use telemetry::{ - propagation, spans, BatchProcessingConfig, JaegerConfig, OtlpConfig, SamplingConfig, - SamplingStrategy, TelemetryConfig, TelemetryError, TelemetryManager, ZipkinConfig, + BatchProcessingConfig, JaegerConfig, OtlpConfig, SamplingConfig, SamplingStrategy, + TelemetryConfig, TelemetryError, TelemetryManager, ZipkinConfig, propagation, spans, }; /// Result type for logging operations diff --git a/mcp-logging/src/metrics_tests.rs b/mcp-logging/src/metrics_tests.rs index 78e4bfdc..01783f01 100644 --- a/mcp-logging/src/metrics_tests.rs +++ b/mcp-logging/src/metrics_tests.rs @@ -3,8 +3,8 @@ #[cfg(test)] mod tests { use super::super::*; - use crate::metrics::current_timestamp; use crate::ErrorClassification; + use crate::metrics::current_timestamp; use std::time::Duration; use tokio::time::sleep; diff --git a/mcp-logging/src/persistence.rs b/mcp-logging/src/persistence.rs index 86dec065..61abb954 100644 --- a/mcp-logging/src/persistence.rs +++ b/mcp-logging/src/persistence.rs @@ -291,7 +291,7 @@ fn parse_file_timestamp(path: &Path, interval: &RotationInterval) -> Option= 19 { let timestamp_str = &filename[8..19]; // Skip "metrics_", extract "YYYYMMDD_HH" - // Parse as "20240107_14" -> parse date and hour separately + // Parse as "20240107_14" -> parse date and hour separately if let Some((date_str, hour_str)) = timestamp_str.split_once('_') { if let (Ok(date), Ok(hour)) = ( NaiveDate::parse_from_str(date_str, "%Y%m%d"), @@ -362,7 +362,9 @@ mod tests { #[tokio::test] async fn test_metrics_persistence() { let _config = PersistenceConfig { - data_dir: std::path::PathBuf::from("/tmp/test_metrics"), + data_dir: std::env::temp_dir() + .join("mcp-logging-persistence-test") + .join("metrics"), rotation_interval: RotationInterval::Never, max_files: 10, compress: false, diff --git a/mcp-logging/src/sanitization_tests.rs b/mcp-logging/src/sanitization_tests.rs index 8dcfd801..f9e7e24a 100644 --- a/mcp-logging/src/sanitization_tests.rs +++ b/mcp-logging/src/sanitization_tests.rs @@ -168,15 +168,15 @@ mod tests { let test_cases = vec![ ( "User ID: 550e8400-e29b-41d4-a716-446655440000", - "User ID: [UUID_REDACTED]" + "User ID: [UUID_REDACTED]", ), ( "session=123e4567-e89b-12d3-a456-426614174000", - "session=[UUID_REDACTED]" + "session=[UUID_REDACTED]", ), ( "Multiple: 550e8400-e29b-41d4-a716-446655440000 and 123e4567-e89b-12d3-a456-426614174000", - "Multiple: [UUID_REDACTED] and [UUID_REDACTED]" + "Multiple: [UUID_REDACTED] and [UUID_REDACTED]", ), ]; diff --git a/mcp-logging/src/structured_tests.rs b/mcp-logging/src/structured_tests.rs index 3351de96..61b1344f 100644 --- a/mcp-logging/src/structured_tests.rs +++ b/mcp-logging/src/structured_tests.rs @@ -22,10 +22,12 @@ mod tests { // Correlation ID should be 24 hex chars (12 bytes) assert_eq!(context.correlation_id.len(), 24); - assert!(context - .correlation_id - .chars() - .all(|c| c.is_ascii_hexdigit())); + assert!( + context + .correlation_id + .chars() + .all(|c| c.is_ascii_hexdigit()) + ); } #[test] diff --git a/mcp-macros/src/lib.rs b/mcp-macros/src/lib.rs index 558ced92..1600956f 100644 --- a/mcp-macros/src/lib.rs +++ b/mcp-macros/src/lib.rs @@ -33,6 +33,8 @@ use proc_macro::TokenStream; mod mcp_backend; +mod mcp_prompt; +mod mcp_resource; mod mcp_server; mod mcp_tool; mod utils; @@ -165,6 +167,116 @@ pub fn mcp_server(attr: TokenStream, item: TokenStream) -> TokenStream { .into() } +/// Automatically generates MCP resource definitions from Rust functions. +/// +/// This macro transforms regular Rust functions into MCP resources with automatic +/// URI template parsing, parameter extraction, and content type handling. +/// +/// # Basic Usage +/// +/// ```rust,ignore +/// use pulseengine_mcp_macros::mcp_resource; +/// +/// #[mcp_resource(uri_template = "file://{path}")] +/// async fn read_file(&self, path: String) -> Result { +/// tokio::fs::read_to_string(&path).await +/// } +/// ``` +/// +/// # With Custom Configuration +/// +/// ```rust,ignore +/// #[mcp_resource( +/// uri_template = "db://{database}/{table}", +/// name = "database_table", +/// description = "Read data from a database table", +/// mime_type = "application/json" +/// )] +/// async fn read_table(&self, database: String, table: String) -> Result { +/// // Implementation +/// } +/// ``` +/// +/// # Parameters +/// +/// - `uri_template`: Required URI template with parameters in `{param}` format +/// - `name`: Optional custom resource name (defaults to function name) +/// - `description`: Optional custom description (defaults to doc comments) +/// - `mime_type`: Optional MIME type (defaults to "text/plain") +/// +/// # Features +/// +/// - **URI Template Parsing**: Automatic extraction of parameters from URI templates +/// - **Type Safety**: Compile-time validation of parameter types +/// - **Auto-Documentation**: Uses function doc comments as resource descriptions +/// - **Content Type Detection**: Automatic MIME type handling +/// - **Error Handling**: Converts function errors to MCP protocol errors +/// +/// # References +/// +/// - [MCP Resources Specification](https://modelcontextprotocol.io/specification/) +/// - [Building with LLMs Tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms) +#[proc_macro_attribute] +pub fn mcp_resource(attr: TokenStream, item: TokenStream) -> TokenStream { + mcp_resource::mcp_resource_impl(attr.into(), item.into()) + .unwrap_or_else(|err| err.to_compile_error()) + .into() +} + +/// Automatically generates MCP prompt definitions from Rust functions. +/// +/// This macro transforms regular Rust functions into MCP prompts with automatic +/// argument validation and prompt message generation. +/// +/// # Basic Usage +/// +/// ```rust,ignore +/// use pulseengine_mcp_macros::mcp_prompt; +/// +/// #[mcp_prompt(name = "code_review")] +/// async fn generate_code_review(&self, code: String, language: String) -> Result { +/// // Generate prompt for code review +/// } +/// ``` +/// +/// # With Custom Configuration +/// +/// ```rust,ignore +/// #[mcp_prompt( +/// name = "sql_query_helper", +/// description = "Generate SQL queries based on natural language", +/// arguments = ["description", "table_schema", "output_format"] +/// )] +/// async fn sql_helper(&self, description: String, table_schema: String, output_format: String) -> Result { +/// // Implementation +/// } +/// ``` +/// +/// # Parameters +/// +/// - `name`: Optional custom prompt name (defaults to function name) +/// - `description`: Optional custom description (defaults to doc comments) +/// - `arguments`: Optional array of argument names for documentation +/// +/// # Features +/// +/// - **Argument Validation**: Automatic validation of prompt arguments +/// - **Type Safety**: Compile-time validation of parameter types +/// - **Auto-Documentation**: Uses function doc comments as prompt descriptions +/// - **Error Handling**: Converts function errors to MCP protocol errors +/// - **Schema Generation**: Automatic argument schema generation +/// +/// # References +/// +/// - [MCP Prompts Specification](https://modelcontextprotocol.io/specification/) +/// - [Building with LLMs Tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms) +#[proc_macro_attribute] +pub fn mcp_prompt(attr: TokenStream, item: TokenStream) -> TokenStream { + mcp_prompt::mcp_prompt_impl(attr.into(), item.into()) + .unwrap_or_else(|err| err.to_compile_error()) + .into() +} + /// Derives MCP tool implementations for all methods in an impl block. /// /// This is a convenience macro that applies `#[mcp_tool]` to all public diff --git a/mcp-macros/src/mcp_backend.rs b/mcp-macros/src/mcp_backend.rs index 3e04bc89..1b358d58 100644 --- a/mcp-macros/src/mcp_backend.rs +++ b/mcp-macros/src/mcp_backend.rs @@ -61,13 +61,20 @@ pub fn mcp_backend_impl(attr: TokenStream, item: TokenStream) -> syn::Result Result { + // Auto-discover resources from methods marked with #[mcp_resource] + let mut resources = Vec::new(); + + // This will be enhanced to automatically collect resources + // from methods with #[mcp_resource] attribute + Ok(pulseengine_mcp_protocol::ListResourcesResult { - resources: vec![], + resources, next_cursor: None, }) } @@ -206,6 +219,8 @@ fn generate_backend_implementation( &self, request: pulseengine_mcp_protocol::ReadResourceRequestParam, ) -> Result { + // Auto-dispatch to resource implementations + // This will be enhanced to automatically route to methods with #[mcp_resource] Err(#error_type_name::InvalidParameter( format!("Resource not found: {}", request.uri) )) @@ -215,8 +230,14 @@ fn generate_backend_implementation( &self, _request: pulseengine_mcp_protocol::PaginatedRequestParam, ) -> Result { + // Auto-discover prompts from methods marked with #[mcp_prompt] + let mut prompts = Vec::new(); + + // This will be enhanced to automatically collect prompts + // from methods with #[mcp_prompt] attribute + Ok(pulseengine_mcp_protocol::ListPromptsResult { - prompts: vec![], + prompts, next_cursor: None, }) } @@ -225,6 +246,8 @@ fn generate_backend_implementation( &self, request: pulseengine_mcp_protocol::GetPromptRequestParam, ) -> Result { + // Auto-dispatch to prompt implementations + // This will be enhanced to automatically route to methods with #[mcp_prompt] Err(#error_type_name::InvalidParameter( format!("Prompt not found: {}", request.name) )) diff --git a/mcp-macros/src/mcp_prompt.rs b/mcp-macros/src/mcp_prompt.rs new file mode 100644 index 00000000..d4ceac38 --- /dev/null +++ b/mcp-macros/src/mcp_prompt.rs @@ -0,0 +1,274 @@ +//! # MCP Prompt Macro Implementation +//! +//! This module implements the `#[mcp_prompt]` macro for automatically generating +//! MCP prompt implementations from Rust functions. Prompts in MCP allow servers +//! to provide reusable prompt templates for AI interactions. +//! +//! ## Key Features +//! - Automatic prompt argument validation and processing +//! - Type-safe parameter handling +//! - Integration with server capabilities auto-detection +//! - Support for both sync and async prompt functions +//! +//! ## References +//! - [MCP Specification](https://modelcontextprotocol.io/specification/) +//! - [Building with LLMs Tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms) + +use proc_macro2::{Span, TokenStream}; +use quote::quote; +use syn::{Error, FnArg, ItemFn, PatType, Result, parse2}; + +use crate::utils::{extract_doc_comments, parse_attribute_args}; + +/// Configuration for the mcp_prompt macro +#[derive(Debug, Default)] +pub struct McpPromptConfig { + /// Name of the prompt (defaults to function name) + pub name: Option, + /// Custom description (defaults to doc comments) + pub description: Option, + /// Arguments that the prompt accepts + pub arguments: Option>, +} + +/// Parse macro attributes into McpPromptConfig +fn parse_prompt_attributes(args: TokenStream) -> Result { + let mut config = McpPromptConfig::default(); + let parsed_args = parse_attribute_args(args)?; + + for (key, value) in parsed_args { + match key.as_str() { + "name" => { + if let syn::Expr::Lit(syn::ExprLit { + lit: syn::Lit::Str(lit_str), + .. + }) = value + { + config.name = Some(lit_str.value()); + } else { + return Err(Error::new_spanned(value, "name must be a string literal")); + } + } + "description" => { + if let syn::Expr::Lit(syn::ExprLit { + lit: syn::Lit::Str(lit_str), + .. + }) = value + { + config.description = Some(lit_str.value()); + } else { + return Err(Error::new_spanned( + value, + "description must be a string literal", + )); + } + } + "arguments" => { + // Parse array of strings for arguments + if let syn::Expr::Array(array) = value { + let mut args = Vec::new(); + for elem in array.elems { + if let syn::Expr::Lit(syn::ExprLit { + lit: syn::Lit::Str(lit_str), + .. + }) = elem + { + args.push(lit_str.value()); + } else { + return Err(Error::new_spanned( + elem, + "argument names must be string literals", + )); + } + } + config.arguments = Some(args); + } else { + return Err(Error::new_spanned( + value, + "arguments must be an array of strings", + )); + } + } + _ => { + return Err(Error::new_spanned( + value, + format!("Unknown attribute: {key}"), + )); + } + } + } + + Ok(config) +} + +/// Generate prompt parameter extraction code +fn generate_prompt_parameter_extraction(fn_inputs: &[&PatType]) -> Result { + let extractions = fn_inputs.iter().map(|pat_type| { + let param_ident = &pat_type.pat; + let param_type = &pat_type.ty; + let param_name = quote!(#param_ident).to_string(); + + quote! { + let #param_ident: #param_type = arguments.get(#param_name) + .ok_or_else(|| pulseengine_mcp_protocol::McpError::InvalidParams { + message: format!("Missing argument: {}", #param_name), + })? + .clone(); + } + }); + + Ok(quote! { + #(#extractions)* + }) +} + +/// Generate the prompt implementation +fn generate_prompt_impl(config: &McpPromptConfig, original_fn: &ItemFn) -> Result { + let fn_name = &original_fn.sig.ident; + let fn_name_string = fn_name.to_string(); + let prompt_name = config.name.as_ref().unwrap_or(&fn_name_string); + let description = config.description.clone().unwrap_or_else(|| { + extract_doc_comments(&original_fn.attrs).unwrap_or_else(|| format!("Prompt: {prompt_name}")) + }); + + // Extract function parameters (excluding &self if present) + let fn_inputs: Vec<&PatType> = original_fn + .sig + .inputs + .iter() + .filter_map(|arg| match arg { + FnArg::Typed(pat_type) => Some(pat_type), + FnArg::Receiver(_) => None, // Skip &self + }) + .collect(); + + // Generate parameter extraction code + let param_extraction = generate_prompt_parameter_extraction(&fn_inputs)?; + + // Generate argument schema for prompt info + let argument_schemas = fn_inputs.iter().map(|pat_type| { + let param_name = quote!(#pat_type.pat).to_string(); + let param_type = &pat_type.ty; + + quote! { + serde_json::json!({ + "name": #param_name, + "description": format!("Parameter of type {}", stringify!(#param_type)), + "required": true + }) + } + }); + + // Determine if function is async + let is_async = original_fn.sig.asyncness.is_some(); + let await_token = if is_async { quote!(.await) } else { quote!() }; + + // Generate the prompt handler function name + let handler_name = syn::Ident::new( + &format!("__mcp_prompt_handler_{fn_name}"), + Span::call_site(), + ); + + // Generate parameter passing for function call + let param_names: Vec<_> = fn_inputs.iter().map(|p| &p.pat).collect(); + + Ok(quote! { + // Original function (unchanged) + #original_fn + + // Generated prompt handler + pub async fn #handler_name( + &self, + name: &str, + arguments: &std::collections::HashMap, + ) -> Result { + // Extract parameters from arguments + #param_extraction + + // Call the original function + let result = self.#fn_name(#(#param_names),*)#await_token; + + // Convert result to GetPromptResult + match result { + Ok(prompt_message) => { + Ok(pulseengine_mcp_protocol::GetPromptResult { + description: Some(#description.to_string()), + messages: vec![prompt_message], + }) + } + Err(e) => Err(pulseengine_mcp_protocol::McpError::InternalError { + message: format!("Prompt error: {}", e), + }), + } + } + + // Prompt metadata for capability registration + pub fn __mcp_prompt_info() -> pulseengine_mcp_protocol::Prompt { + pulseengine_mcp_protocol::Prompt { + name: #prompt_name.to_string(), + description: Some(#description.to_string()), + arguments: Some(vec![#(#argument_schemas),*]), + } + } + }) +} + +/// Main implementation function for the mcp_prompt macro +pub fn mcp_prompt_impl(args: TokenStream, input: TokenStream) -> Result { + // Parse the configuration from macro arguments + let config = parse_prompt_attributes(args)?; + + // Parse the function + let original_fn: ItemFn = parse2(input)?; + + // Validate function signature + if original_fn.sig.inputs.is_empty() { + return Err(Error::new_spanned( + &original_fn.sig, + "Prompt functions must have at least one parameter", + )); + } + + // Generate the implementation + generate_prompt_impl(&config, &original_fn) +} + +#[cfg(test)] +mod tests { + use super::*; + use quote::quote; + + #[test] + fn test_parse_prompt_attributes() { + let args = quote! { + name = "code_review", + description = "Generate a code review prompt" + }; + + let config = parse_prompt_attributes(args).unwrap(); + assert_eq!(config.name, Some("code_review".to_string())); + assert_eq!( + config.description, + Some("Generate a code review prompt".to_string()) + ); + } + + #[test] + fn test_parse_prompt_attributes_with_arguments() { + let args = quote! { + name = "test_prompt", + arguments = ["code", "language", "style"] + }; + + let config = parse_prompt_attributes(args).unwrap(); + assert_eq!(config.name, Some("test_prompt".to_string())); + assert_eq!( + config.arguments, + Some(vec![ + "code".to_string(), + "language".to_string(), + "style".to_string() + ]) + ); + } +} diff --git a/mcp-macros/src/mcp_resource.rs b/mcp-macros/src/mcp_resource.rs new file mode 100644 index 00000000..984adf18 --- /dev/null +++ b/mcp-macros/src/mcp_resource.rs @@ -0,0 +1,324 @@ +//! # MCP Resource Macro Implementation +//! +//! This module implements the `#[mcp_resource]` macro for automatically generating +//! MCP resource implementations from Rust functions. Resources in MCP allow servers +//! to expose data that clients can read. +//! +//! ## Key Features +//! - Automatic URI template parsing and validation +//! - Type-safe parameter extraction from URIs +//! - Integration with server capabilities auto-detection +//! - Support for both sync and async resource functions +//! +//! ## References +//! - [MCP Specification](https://modelcontextprotocol.io/specification/) +//! - [Building with LLMs Tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms) + +use proc_macro2::{Span, TokenStream}; +use quote::quote; +use syn::{Error, FnArg, ItemFn, PatType, Result, parse2}; + +use crate::utils::{extract_doc_comments, parse_attribute_args}; + +/// Configuration for the mcp_resource macro +#[derive(Debug, Default)] +pub struct McpResourceConfig { + /// URI template for the resource (e.g., "file://{path}") + pub uri_template: Option, + /// Custom name for the resource (defaults to function name) + pub name: Option, + /// Custom description (defaults to doc comments) + pub description: Option, + /// MIME type of the resource content + pub mime_type: Option, +} + +/// Parse macro attributes into McpResourceConfig +fn parse_resource_attributes(args: TokenStream) -> Result { + let mut config = McpResourceConfig::default(); + let parsed_args = parse_attribute_args(args)?; + + for (key, value) in parsed_args { + match key.as_str() { + "uri_template" => { + if let syn::Expr::Lit(syn::ExprLit { + lit: syn::Lit::Str(lit_str), + .. + }) = value + { + config.uri_template = Some(lit_str.value()); + } else { + return Err(Error::new_spanned( + value, + "uri_template must be a string literal", + )); + } + } + "name" => { + if let syn::Expr::Lit(syn::ExprLit { + lit: syn::Lit::Str(lit_str), + .. + }) = value + { + config.name = Some(lit_str.value()); + } else { + return Err(Error::new_spanned(value, "name must be a string literal")); + } + } + "description" => { + if let syn::Expr::Lit(syn::ExprLit { + lit: syn::Lit::Str(lit_str), + .. + }) = value + { + config.description = Some(lit_str.value()); + } else { + return Err(Error::new_spanned( + value, + "description must be a string literal", + )); + } + } + "mime_type" => { + if let syn::Expr::Lit(syn::ExprLit { + lit: syn::Lit::Str(lit_str), + .. + }) = value + { + config.mime_type = Some(lit_str.value()); + } else { + return Err(Error::new_spanned( + value, + "mime_type must be a string literal", + )); + } + } + _ => { + return Err(Error::new_spanned( + value, + format!("Unknown attribute: {key}"), + )); + } + } + } + + // Validate that uri_template is provided + if config.uri_template.is_none() { + return Err(Error::new( + Span::call_site(), + "uri_template is required for mcp_resource", + )); + } + + Ok(config) +} + +/// Extract URI template parameters (e.g., "{path}" from "file://{path}") +fn extract_uri_parameters(uri_template: &str) -> Vec { + let mut params = Vec::new(); + let mut chars = uri_template.chars().peekable(); + + while let Some(ch) = chars.next() { + if ch == '{' { + let mut param = String::new(); + for ch in chars.by_ref() { + if ch == '}' { + if !param.is_empty() { + params.push(param); + } + break; + } + param.push(ch); + } + } + } + + params +} + +/// Generate resource parameter extraction code +fn generate_parameter_extraction( + uri_params: &[String], + fn_inputs: &[&PatType], +) -> Result { + if uri_params.len() != fn_inputs.len() { + return Err(Error::new( + Span::call_site(), + format!( + "URI template has {} parameters but function has {} parameters", + uri_params.len(), + fn_inputs.len() + ), + )); + } + + let extractions = uri_params + .iter() + .zip(fn_inputs.iter()) + .map(|(param_name, pat_type)| { + let param_ident = &pat_type.pat; + let param_type = &pat_type.ty; + + quote! { + let #param_ident: #param_type = uri_params.get(#param_name) + .ok_or_else(|| pulseengine_mcp_protocol::McpError::InvalidParams { + message: format!("Missing parameter: {}", #param_name), + })? + .parse() + .map_err(|e| pulseengine_mcp_protocol::McpError::InvalidParams { + message: format!("Invalid parameter {}: {}", #param_name, e), + })?; + } + }); + + Ok(quote! { + #(#extractions)* + }) +} + +/// Generate the resource implementation +fn generate_resource_impl(config: &McpResourceConfig, original_fn: &ItemFn) -> Result { + let fn_name = &original_fn.sig.ident; + let fn_name_string = fn_name.to_string(); + let resource_name = config.name.as_ref().unwrap_or(&fn_name_string); + let uri_template = config.uri_template.as_ref().unwrap(); + let description = config.description.clone().unwrap_or_else(|| { + extract_doc_comments(&original_fn.attrs) + .unwrap_or_else(|| format!("Resource: {resource_name}")) + }); + let default_mime_type = "text/plain".to_string(); + let mime_type = config.mime_type.as_ref().unwrap_or(&default_mime_type); + + // Extract URI parameters + let uri_params = extract_uri_parameters(uri_template); + + // Extract function parameters (excluding &self if present) + let fn_inputs: Vec<&PatType> = original_fn + .sig + .inputs + .iter() + .filter_map(|arg| match arg { + FnArg::Typed(pat_type) => Some(pat_type), + FnArg::Receiver(_) => None, // Skip &self + }) + .collect(); + + // Generate parameter extraction code + let param_extraction = generate_parameter_extraction(&uri_params, &fn_inputs)?; + + // Generate parameter names for function call + let param_names: Vec<_> = fn_inputs.iter().map(|p| &p.pat).collect(); + + // Determine if function is async + let is_async = original_fn.sig.asyncness.is_some(); + let await_token = if is_async { quote!(.await) } else { quote!() }; + + // Generate the resource handler function name + let handler_name = syn::Ident::new( + &format!("__mcp_resource_handler_{fn_name}"), + Span::call_site(), + ); + + Ok(quote! { + // Original function (unchanged) + #original_fn + + // Generated resource handler + pub async fn #handler_name( + &self, + uri: &str, + uri_params: &std::collections::HashMap, + ) -> Result { + // Extract parameters from URI + #param_extraction + + // Call the original function + let result = self.#fn_name(#(#param_names),*)#await_token; + + // Convert result to ResourceContents + match result { + Ok(content) => { + let content_str = match serde_json::to_string(&content) { + Ok(json) => json, + Err(_) => content.to_string(), // Fallback to Display/Debug + }; + + Ok(pulseengine_mcp_protocol::ResourceContents { + uri: uri.to_string(), + mime_type: Some(#mime_type.to_string()), + text: Some(content_str), + blob: None, + }) + } + Err(e) => Err(pulseengine_mcp_protocol::McpError::InternalError { + message: format!("Resource error: {}", e), + }), + } + } + + // Resource metadata for capability registration + pub fn __mcp_resource_info() -> pulseengine_mcp_protocol::Resource { + pulseengine_mcp_protocol::Resource { + uri: #uri_template.to_string(), + name: Some(#resource_name.to_string()), + description: Some(#description.to_string()), + mime_type: Some(#mime_type.to_string()), + } + } + }) +} + +/// Main implementation function for the mcp_resource macro +pub fn mcp_resource_impl(args: TokenStream, input: TokenStream) -> Result { + // Parse the configuration from macro arguments + let config = parse_resource_attributes(args)?; + + // Parse the function + let original_fn: ItemFn = parse2(input)?; + + // Validate function signature + if original_fn.sig.inputs.is_empty() { + return Err(Error::new_spanned( + &original_fn.sig, + "Resource functions must have at least one parameter", + )); + } + + // Generate the implementation + generate_resource_impl(&config, &original_fn) +} + +#[cfg(test)] +mod tests { + use super::*; + use quote::quote; + + #[test] + fn test_extract_uri_parameters() { + assert_eq!(extract_uri_parameters("file://{path}"), vec!["path"]); + + assert_eq!( + extract_uri_parameters("db://{database}/{table}"), + vec!["database", "table"] + ); + + assert_eq!( + extract_uri_parameters("static://content"), + Vec::::new() + ); + } + + #[test] + fn test_parse_resource_attributes() { + let args = quote! { + uri_template = "file://{path}", + name = "file_reader", + mime_type = "application/json" + }; + + let config = parse_resource_attributes(args).unwrap(); + assert_eq!(config.uri_template, Some("file://{path}".to_string())); + assert_eq!(config.name, Some("file_reader".to_string())); + assert_eq!(config.mime_type, Some("application/json".to_string())); + } +} diff --git a/mcp-macros/src/mcp_server.rs b/mcp-macros/src/mcp_server.rs index 9363c6f9..74b4a61c 100644 --- a/mcp-macros/src/mcp_server.rs +++ b/mcp-macros/src/mcp_server.rs @@ -195,8 +195,13 @@ fn generate_server_implementation( tools: Some(pulseengine_mcp_protocol::ToolsCapability { list_changed: Some(false), }), - resources: None, - prompts: None, + resources: Some(pulseengine_mcp_protocol::ResourcesCapability { + subscribe: Some(false), + list_changed: Some(false), + }), + prompts: Some(pulseengine_mcp_protocol::PromptsCapability { + list_changed: Some(false), + }), logging: Some(pulseengine_mcp_protocol::LoggingCapability { level: Some("info".to_string()), }), @@ -250,8 +255,15 @@ fn generate_server_implementation( &self, _request: pulseengine_mcp_protocol::PaginatedRequestParam, ) -> Result { + // Auto-discover resources from methods marked with #[mcp_resource] + let mut resources = Vec::new(); + + // Get resources from automatic resource discovery (if #[mcp_resource] methods exist) + let automatic_resources = self.get_automatic_resources(); + resources.extend(automatic_resources); + Ok(pulseengine_mcp_protocol::ListResourcesResult { - resources: vec![], + resources, next_cursor: None, }) } @@ -260,6 +272,11 @@ fn generate_server_implementation( &self, request: pulseengine_mcp_protocol::ReadResourceRequestParam, ) -> Result { + // Try automatic resource dispatch (if #[mcp_resource] methods exist) + if let Some(result) = self.dispatch_automatic_resource(request.clone()).await { + return result.map_err(|e| #error_type_name::InvalidParameter(format!("Resource error: {}", e))); + } + Err(#error_type_name::InvalidParameter( format!("Resource not found: {}", request.uri) )) @@ -269,8 +286,15 @@ fn generate_server_implementation( &self, _request: pulseengine_mcp_protocol::PaginatedRequestParam, ) -> Result { + // Auto-discover prompts from methods marked with #[mcp_prompt] + let mut prompts = Vec::new(); + + // Get prompts from automatic prompt discovery (if #[mcp_prompt] methods exist) + let automatic_prompts = self.get_automatic_prompts(); + prompts.extend(automatic_prompts); + Ok(pulseengine_mcp_protocol::ListPromptsResult { - prompts: vec![], + prompts, next_cursor: None, }) } @@ -279,6 +303,11 @@ fn generate_server_implementation( &self, request: pulseengine_mcp_protocol::GetPromptRequestParam, ) -> Result { + // Try automatic prompt dispatch (if #[mcp_prompt] methods exist) + if let Some(result) = self.dispatch_automatic_prompt(request.clone()).await { + return result.map_err(|e| #error_type_name::InvalidParameter(format!("Prompt error: {}", e))); + } + Err(#error_type_name::InvalidParameter( format!("Prompt not found: {}", request.name) )) @@ -297,9 +326,9 @@ fn generate_server_implementation( ) -> std::pin::Pin> + Send + '_>>; } - // Integration point for automatic tool discovery + // Integration points for automatic discovery // The methods below provide integration hooks that will be used if the corresponding - // methods are generated by the #[mcp_tools] macro + // methods are generated by #[mcp_tools], #[mcp_resource], or #[mcp_prompt] macros impl #impl_generics #struct_name #ty_generics #where_clause { /// Integration hook for automatic tool discovery /// This method is designed to be compatible with tools generated by #[mcp_tools] @@ -324,6 +353,48 @@ fn generate_server_implementation( // and the user manually calls it from their implementation None } + + /// Integration hook for automatic resource discovery + /// This method is designed to be compatible with resources generated by #[mcp_resource] + #[allow(unused_variables)] + fn get_automatic_resources(&self) -> Vec { + // Default implementation returns empty vec + // This will be enhanced to collect resources from methods with #[mcp_resource] + Vec::new() + } + + /// Integration hook for automatic resource dispatch + /// This method is designed to be compatible with dispatch generated by #[mcp_resource] + #[allow(unused_variables)] + async fn dispatch_automatic_resource( + &self, + request: pulseengine_mcp_protocol::ReadResourceRequestParam, + ) -> Option> { + // Default implementation returns None (no automatic resources available) + // This will be enhanced to route to methods with #[mcp_resource] + None + } + + /// Integration hook for automatic prompt discovery + /// This method is designed to be compatible with prompts generated by #[mcp_prompt] + #[allow(unused_variables)] + fn get_automatic_prompts(&self) -> Vec { + // Default implementation returns empty vec + // This will be enhanced to collect prompts from methods with #[mcp_prompt] + Vec::new() + } + + /// Integration hook for automatic prompt dispatch + /// This method is designed to be compatible with dispatch generated by #[mcp_prompt] + #[allow(unused_variables)] + async fn dispatch_automatic_prompt( + &self, + request: pulseengine_mcp_protocol::GetPromptRequestParam, + ) -> Option> { + // Default implementation returns None (no automatic prompts available) + // This will be enhanced to route to methods with #[mcp_prompt] + None + } } // Fluent builder API - this is where the magic happens! diff --git a/mcp-macros/src/mcp_tool.rs b/mcp-macros/src/mcp_tool.rs index aee3b3b6..28b43915 100644 --- a/mcp-macros/src/mcp_tool.rs +++ b/mcp-macros/src/mcp_tool.rs @@ -1,8 +1,8 @@ //! Implementation of the #[mcp_tool] macro -use darling::{ast::NestedMeta, FromMeta}; +use darling::{FromMeta, ast::NestedMeta}; use proc_macro2::TokenStream; -use quote::{format_ident, quote, ToTokens}; +use quote::{ToTokens, format_ident, quote}; use syn::{ImplItemFn, ItemFn, ItemImpl, ReturnType}; use crate::utils::*; diff --git a/mcp-macros/src/utils.rs b/mcp-macros/src/utils.rs index d09c336b..b55ecf26 100644 --- a/mcp-macros/src/utils.rs +++ b/mcp-macros/src/utils.rs @@ -4,6 +4,61 @@ use proc_macro2::TokenStream; use quote::quote; use syn::{Attribute, Expr, Lit, Meta}; +/// Custom parser for attribute arguments +struct AttributeArgs { + args: Vec<(String, Expr)>, +} + +impl syn::parse::Parse for AttributeArgs { + fn parse(input: syn::parse::ParseStream) -> syn::Result { + let mut args = Vec::new(); + + while !input.is_empty() { + let meta: syn::Meta = input.parse()?; + + match meta { + syn::Meta::NameValue(name_value) => { + let key = name_value + .path + .get_ident() + .ok_or_else(|| { + syn::Error::new_spanned(&name_value.path, "Expected identifier") + })? + .to_string(); + args.push((key, name_value.value)); + } + _ => { + return Err(syn::Error::new_spanned( + meta, + "Expected name-value pairs like key = \"value\"", + )); + } + } + + if input.peek(syn::Token![,]) { + input.parse::()?; + } + } + + Ok(AttributeArgs { args }) + } +} + +/// Parse attribute arguments into a vector of key-value pairs +pub fn parse_attribute_args(args: TokenStream) -> syn::Result> { + if args.is_empty() { + return Ok(Vec::new()); + } + + let parsed = syn::parse2::(args)?; + Ok(parsed.args) +} + +/// Extract documentation from function attributes (alias for backward compatibility) +pub fn extract_doc_comments(attrs: &[Attribute]) -> Option { + extract_doc_comment(attrs) +} + /// Extract documentation from function attributes pub fn extract_doc_comment(attrs: &[Attribute]) -> Option { let mut docs = Vec::new(); diff --git a/mcp-macros/tests/app_name_tests.rs b/mcp-macros/tests/app_name_tests.rs index 26cbce40..db2f0bca 100644 --- a/mcp-macros/tests/app_name_tests.rs +++ b/mcp-macros/tests/app_name_tests.rs @@ -15,7 +15,7 @@ mod app_specific_server { use super::*; // Test server with app_name parameter - #[mcp_server(name = "App-Specific Server", app_name = "test-app")] + #[mcp_server(name = "App-Specific Server", app_name = "test-app-app-name-tests")] #[derive(Default, Clone)] pub struct AppSpecificServer; } @@ -26,7 +26,7 @@ mod complex_app_server { // Test server with app_name and other attributes #[mcp_server( name = "Complex App Server", - app_name = "complex-app", + app_name = "complex-app-app-name-tests", version = "2.0.0", description = "A complex server with app-specific configuration" )] diff --git a/mcp-macros/tests/async_sync_tests.rs b/mcp-macros/tests/async_sync_tests.rs new file mode 100644 index 00000000..ce7a4832 --- /dev/null +++ b/mcp-macros/tests/async_sync_tests.rs @@ -0,0 +1,191 @@ +//! Tests for async and sync function handling in macros + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +#[test] +fn test_mixed_async_sync_server() { + #[mcp_server(name = "Mixed Async/Sync Server")] + #[derive(Default, Clone)] + struct MixedServer; + + #[mcp_tools] + #[allow(dead_code)] + impl MixedServer { + /// Synchronous tool + pub fn sync_tool(&self, input: String) -> String { + format!("Sync: {input}") + } + + /// Asynchronous tool + pub async fn async_tool(&self, input: String) -> String { + tokio::time::sleep(tokio::time::Duration::from_millis(1)).await; + format!("Async: {input}") + } + + /// Synchronous tool with Result + pub fn sync_result_tool(&self, value: i32) -> Result { + if value < 0 { + Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Negative value", + )) + } else { + Ok(value * 2) + } + } + + /// Asynchronous tool with Result + pub async fn async_result_tool(&self, value: i32) -> Result { + tokio::time::sleep(tokio::time::Duration::from_millis(1)).await; + if value == 0 { + Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Zero value", + )) + } else { + Ok(value * 3) + } + } + + /// Complex async tool with multiple parameters + pub async fn complex_async_tool(&self, name: String, age: u32, active: bool) -> String { + tokio::time::sleep(tokio::time::Duration::from_millis(1)).await; + format!( + "User {name} is {age} years old and {}", + if active { "active" } else { "inactive" } + ) + } + + /// Complex sync tool with optional parameters + pub fn complex_sync_tool(&self, required: String, optional: Option) -> String { + match optional { + Some(opt) => format!("Required: {required}, Optional: {opt}"), + None => format!("Required: {required}, Optional: None"), + } + } + } + + let _server = MixedServer::with_defaults(); +} + +#[test] +fn test_pure_sync_server() { + #[mcp_server(name = "Pure Sync Server")] + #[derive(Default, Clone)] + struct PureSyncServer; + + #[mcp_tools] + #[allow(dead_code)] + impl PureSyncServer { + /// All tools are synchronous + pub fn calculate(&self, a: f64, b: f64) -> f64 { + a + b + } + + pub fn format_text(&self, text: String, uppercase: bool) -> String { + if uppercase { + text.to_uppercase() + } else { + text.to_lowercase() + } + } + + pub fn validate_input(&self, input: String) -> Result { + if input.len() < 3 { + Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Input too short", + )) + } else { + Ok(format!("Valid: {input}")) + } + } + } + + let _server = PureSyncServer::with_defaults(); +} + +#[test] +fn test_return_type_combinations() { + #[mcp_server(name = "Return Type Test Server")] + #[derive(Default, Clone)] + struct ReturnTypeServer; + + #[mcp_tools] + #[allow(dead_code)] + impl ReturnTypeServer { + // String return + pub fn string_return(&self) -> String { + "test".to_string() + } + + // Result return + pub fn result_return(&self) -> Result { + Ok("test".to_string()) + } + + // Async string return + pub async fn async_string_return(&self) -> String { + "async test".to_string() + } + + // Async result return + pub async fn async_result_return(&self) -> Result { + Ok("async test".to_string()) + } + + // Complex types + pub fn json_return(&self) -> serde_json::Value { + serde_json::json!({"test": "value"}) + } + + pub fn vec_return(&self) -> Vec { + vec!["a".to_string(), "b".to_string()] + } + } + + let _server = ReturnTypeServer::with_defaults(); +} + +#[test] +fn test_parameter_combinations() { + #[mcp_server(name = "Parameter Test Server")] + #[derive(Default, Clone)] + struct ParameterServer; + + #[mcp_tools] + #[allow(dead_code)] + impl ParameterServer { + // No parameters (besides &self) + pub fn no_params(&self) -> String { + "no params".to_string() + } + + // Single parameter + pub fn single_param(&self, input: String) -> String { + input + } + + // Multiple parameters + pub fn multiple_params(&self, a: String, b: i32, c: bool) -> String { + format!("{a}-{b}-{c}") + } + + // Optional parameters + pub fn optional_params(&self, required: String, optional: Option) -> String { + format!("Required: {required}, Optional: {optional:?}") + } + + // Vector parameters + pub fn vec_params(&self, items: Vec) -> String { + items.join(",") + } + + // JSON parameter + pub fn json_param(&self, data: serde_json::Value) -> String { + data.to_string() + } + } + + let _server = ParameterServer::with_defaults(); +} diff --git a/mcp-macros/tests/backend_integration_tests.rs b/mcp-macros/tests/backend_integration_tests.rs new file mode 100644 index 00000000..437d8557 --- /dev/null +++ b/mcp-macros/tests/backend_integration_tests.rs @@ -0,0 +1,145 @@ +//! Tests for mcp_backend macro integration and functionality + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; +use pulseengine_mcp_server::McpBackend; + +mod simple_backend { + use super::*; + + #[mcp_server(name = "Simple Backend")] + #[derive(Default, Clone)] + pub struct SimpleBackend { + #[allow(dead_code)] + data: String, + } + + #[mcp_tools] + impl SimpleBackend { + /// Echo the input string + pub async fn echo(&self, input: String) -> String { + format!("Echo: {input}") + } + } +} + +mod complex_backend { + use super::*; + + /// A complex backend with custom configuration + #[mcp_server( + name = "Complex Backend", + version = "2.1.0", + description = "A sophisticated MCP backend with advanced features" + )] + #[derive(Clone)] + pub struct ComplexBackend { + counter: std::sync::Arc, + config: String, + } + + impl Default for ComplexBackend { + fn default() -> Self { + Self { + counter: std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0)), + config: "default".to_string(), + } + } + } + + #[mcp_tools] + impl ComplexBackend { + /// Increment and return counter + pub async fn increment(&self) -> u64 { + self.counter + .fetch_add(1, std::sync::atomic::Ordering::SeqCst) + + 1 + } + + /// Get current counter value + pub async fn get_count(&self) -> u64 { + self.counter.load(std::sync::atomic::Ordering::SeqCst) + } + + /// Process data with configuration + pub async fn process_data(&self, data: String) -> String { + format!("Processed '{}' with config '{}'", data, self.config) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use complex_backend::*; + use simple_backend::*; + + #[test] + fn test_simple_backend_compiles() { + let _backend = SimpleBackend::with_defaults(); + } + + #[test] + fn test_complex_backend_compiles() { + let _backend = ComplexBackend::with_defaults(); + } + + #[test] + fn test_backend_server_info() { + let simple = SimpleBackend::with_defaults(); + let complex = ComplexBackend::with_defaults(); + let simple_info = simple.get_server_info(); + let complex_info = complex.get_server_info(); + + assert_eq!(simple_info.server_info.name, "Simple Backend"); + assert_eq!(complex_info.server_info.name, "Complex Backend"); + assert_eq!(complex_info.server_info.version, "2.1.0"); + + // Check capabilities are properly set + assert!(simple_info.capabilities.tools.is_some()); + assert!(complex_info.capabilities.tools.is_some()); + + // Resources and prompts should be enabled by default + assert!(simple_info.capabilities.resources.is_some()); + assert!(simple_info.capabilities.prompts.is_some()); + } + + #[tokio::test] + async fn test_backend_health_check() { + let simple = SimpleBackend::with_defaults(); + let complex = ComplexBackend::with_defaults(); + assert!(simple.health_check().await.is_ok()); + assert!(complex.health_check().await.is_ok()); + } + + #[tokio::test] + async fn test_simple_backend_tools() { + let backend = SimpleBackend::with_defaults(); + let result = backend.echo("test message".to_string()).await; + assert_eq!(result, "Echo: test message"); + } + + #[tokio::test] + async fn test_complex_backend_tools() { + let backend = ComplexBackend::with_defaults(); + + // Test counter functionality + let count1 = backend.increment().await; + let count2 = backend.increment().await; + let current = backend.get_count().await; + + assert_eq!(count1, 1); + assert_eq!(count2, 2); + assert_eq!(current, 2); + + // Test data processing + let result = backend.process_data("hello".to_string()).await; + assert_eq!(result, "Processed 'hello' with config 'default'"); + } + + #[test] + fn test_error_types_exist() { + // Test that error types were generated + let _simple_error = SimpleBackendError::Internal("test".to_string()); + let _complex_error = ComplexBackendError::Internal("test".to_string()); + } +} diff --git a/mcp-macros/tests/documentation_tests.rs b/mcp-macros/tests/documentation_tests.rs new file mode 100644 index 00000000..b0436df9 --- /dev/null +++ b/mcp-macros/tests/documentation_tests.rs @@ -0,0 +1,270 @@ +//! Tests for documentation extraction and formatting + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +#[test] +fn test_documented_server() { + /// This is a comprehensive server example + /// + /// It demonstrates various documentation patterns: + /// - Multi-line descriptions + /// - Code examples + /// - Usage notes + /// + /// # Example + /// + /// ```rust,ignore + /// let server = DocumentedServer::with_defaults(); + /// ``` + #[mcp_server(name = "Documented Server")] + #[derive(Default, Clone)] + struct DocumentedServer; + + #[mcp_tools] + #[allow(dead_code)] + impl DocumentedServer { + /// Process text data with various options + /// + /// This tool can: + /// - Transform text case + /// - Apply filters + /// - Generate summaries + /// + /// # Parameters + /// + /// - `text`: The input text to process + /// - `operation`: The operation to perform + /// - `case_sensitive`: Whether to apply case-sensitive operations + /// + /// # Returns + /// + /// Returns the processed text as a `String`. + /// + /// # Examples + /// + /// ```ignore + /// let result = server.process_text_data("Hello World", "uppercase", false); + /// ``` + pub async fn process_text_data( + &self, + text: String, + operation: String, + case_sensitive: bool, + ) -> String { + match operation.as_str() { + "uppercase" => { + // For this example, both case_sensitive and non-case_sensitive do the same thing + let _ = case_sensitive; // Acknowledge the parameter + text.to_uppercase() + } + "lowercase" => text.to_lowercase(), + "reverse" => text.chars().rev().collect(), + _ => text, + } + } + + /// Generate comprehensive analytics for data processing + /// + /// This tool provides detailed analytics including: + /// - Processing statistics + /// - Performance metrics + /// - Usage patterns + /// - Error rates + /// + /// The analytics are computed in real-time and provide + /// insights into system behavior and performance. + pub fn get_analytics(&self) -> serde_json::Value { + serde_json::json!({ + "total_requests": 100, + "success_rate": 0.95, + "avg_response_time_ms": 45.2, + "peak_requests_per_second": 150, + "error_breakdown": { + "validation_errors": 3, + "timeout_errors": 1, + "system_errors": 1 + }, + "performance_metrics": { + "cpu_usage_percent": 25.3, + "memory_usage_mb": 128.7, + "disk_io_mb_per_sec": 2.1 + } + }) + } + + /// Tool with minimal documentation + pub async fn simple_tool(&self) -> String { + "Simple result".to_string() + } + + /// Single line documentation + pub async fn single_line_doc(&self) -> String { + "Single line result".to_string() + } + } + + let _server = DocumentedServer::with_defaults(); +} + +#[test] +fn test_parameter_documentation() { + #[mcp_server(name = "Parameter Doc Server")] + #[derive(Default, Clone)] + struct ParameterDocServer; + + #[mcp_tools] + #[allow(dead_code)] + impl ParameterDocServer { + /// Tool with extensively documented parameters + /// + /// # Parameters + /// + /// * `user_id` - Unique identifier for the user (must be positive) + /// * `action` - The action to perform (supported: "create", "update", "delete") + /// * `data` - JSON data payload containing the operation details + /// * `dry_run` - If true, validate operation without executing it + /// * `options` - Optional configuration parameters + /// + /// # Returns + /// + /// Returns operation result with status and details + pub async fn documented_operation( + &self, + user_id: u64, + action: String, + data: serde_json::Value, + dry_run: bool, + options: Option, + ) -> serde_json::Value { + serde_json::json!({ + "user_id": user_id, + "action": action, + "data": data, + "dry_run": dry_run, + "options": options, + "status": "success", + "timestamp": "2024-01-01T00:00:00Z" + }) + } + + /// Tool demonstrating complex return type documentation + /// + /// Returns a structured result containing: + /// - `items`: Array of processed items + /// - `metadata`: Processing metadata and statistics + /// - `pagination`: Pagination information if applicable + /// - `errors`: Any non-fatal errors encountered during processing + pub fn complex_return_documentation(&self) -> serde_json::Value { + serde_json::json!({ + "items": [ + {"id": 1, "name": "Item 1", "processed": true}, + {"id": 2, "name": "Item 2", "processed": true} + ], + "metadata": { + "total_items": 2, + "processing_time_ms": 150, + "version": "1.0.0" + }, + "pagination": { + "page": 1, + "per_page": 10, + "total_pages": 1 + }, + "errors": [] + }) + } + } + + let _server = ParameterDocServer::with_defaults(); +} + +#[test] +fn test_example_documentation() { + #[mcp_server(name = "Example Doc Server")] + #[derive(Default, Clone)] + struct ExampleDocServer; + + #[mcp_tools] + #[allow(dead_code)] + impl ExampleDocServer { + /// Mathematical operations with comprehensive examples + /// + /// This tool performs various mathematical operations on the input values. + /// + /// # Examples + /// + /// Basic addition: + /// ```ignore + /// let result = server.math_operation(5.0, 3.0, "add").await; + /// assert_eq!(result, 8.0); + /// ``` + /// + /// Division with error handling: + /// ```ignore + /// let result = server.math_operation(10.0, 0.0, "divide").await; + /// // Returns NaN for division by zero + /// ``` + /// + /// Supported operations: + /// - `add`: Addition (a + b) + /// - `subtract`: Subtraction (a - b) + /// - `multiply`: Multiplication (a * b) + /// - `divide`: Division (a / b, returns NaN if b is 0) + /// - `power`: Exponentiation (a^b) + pub async fn math_operation(&self, a: f64, b: f64, operation: String) -> f64 { + match operation.as_str() { + "add" => a + b, + "subtract" => a - b, + "multiply" => a * b, + "divide" => { + if b == 0.0 { + f64::NAN + } else { + a / b + } + } + "power" => a.powf(b), + _ => f64::NAN, + } + } + + /// String manipulation with usage examples + /// + /// # Usage Examples + /// + /// Transform text to title case: + /// ```ignore + /// let result = server.string_transform("hello world", "title").await; + /// // Returns "Hello World" + /// ``` + /// + /// Reverse a string: + /// ```ignore + /// let result = server.string_transform("hello", "reverse").await; + /// // Returns "olleh" + /// ``` + pub async fn string_transform(&self, input: String, transform: String) -> String { + match transform.as_str() { + "title" => input + .split_whitespace() + .map(|word| { + let mut chars = word.chars(); + match chars.next() { + None => String::new(), + Some(first) => { + first.to_uppercase().collect::() + + &chars.as_str().to_lowercase() + } + } + }) + .collect::>() + .join(" "), + "reverse" => input.chars().rev().collect(), + "snake_case" => input.to_lowercase().replace(' ', "_"), + _ => input, + } + } + } + + let _server = ExampleDocServer::with_defaults(); +} diff --git a/mcp-macros/tests/error_handling_tests.rs b/mcp-macros/tests/error_handling_tests.rs new file mode 100644 index 00000000..68856213 --- /dev/null +++ b/mcp-macros/tests/error_handling_tests.rs @@ -0,0 +1,291 @@ +//! Tests for error handling across all macro types + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; +use pulseengine_mcp_protocol::{PromptMessage, PromptMessageRole}; + +mod error_backend { + use super::*; + + #[derive(Debug, thiserror::Error)] + pub enum CustomError { + #[error("Custom error: {0}")] + Custom(String), + #[error("Network error")] + Network, + #[error("Validation error: {field}")] + Validation { field: String }, + } + + #[mcp_server(name = "Error Backend")] + #[derive(Default, Clone)] + pub struct ErrorBackend; + + #[mcp_tools] + impl ErrorBackend { + /// Tool that always succeeds + pub async fn success_tool(&self, input: String) -> String { + format!("Success: {input}") + } + + /// Tool that returns a custom error + pub async fn error_tool(&self, _input: String) -> Result { + Err(CustomError::Custom("This tool always fails".to_string())) + } + + /// Tool that returns a standard error + pub async fn io_error_tool(&self, _input: String) -> Result { + Err(std::io::Error::new( + std::io::ErrorKind::NotFound, + "File not found", + )) + } + + /// Tool with validation error + pub async fn validation_tool(&self, name: String) -> Result { + if name.is_empty() { + Err(CustomError::Validation { + field: "name".to_string(), + }) + } else { + Ok(format!("Valid name: {name}")) + } + } + } +} + +mod error_server { + use super::*; + + #[mcp_server(name = "Error Server")] + #[derive(Default, Clone)] + pub struct ErrorServer; + + #[mcp_tools] + impl ErrorServer { + /// Resource that may fail + pub async fn error_resource(&self, error_type: String) -> Result { + match error_type.as_str() { + "success" => Ok("Resource data".to_string()), + "not_found" => Err(std::io::Error::new( + std::io::ErrorKind::NotFound, + "Resource not found", + )), + "permission" => Err(std::io::Error::new( + std::io::ErrorKind::PermissionDenied, + "Permission denied", + )), + _ => Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + "Invalid error type", + )), + } + } + + /// Prompt that may fail + pub async fn error_prompt( + &self, + prompt_type: String, + ) -> Result { + match prompt_type.as_str() { + "success" => Ok(PromptMessage { + role: PromptMessageRole::User, + content: pulseengine_mcp_protocol::PromptMessageContent::Text { + text: "Successful prompt".to_string(), + }, + }), + "invalid" => Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Invalid prompt type", + )), + _ => Err(std::io::Error::other("Unknown prompt type")), + } + } + + /// Tool with multiple error conditions + pub async fn complex_error_tool( + &self, + operation: String, + value: i32, + ) -> Result> { + match operation.as_str() { + "divide" => { + if value == 0 { + Err("Division by zero".into()) + } else { + Ok(format!("Result: {}", 100 / value)) + } + } + "parse" => { + let parsed: i32 = value.to_string().parse()?; + Ok(format!("Parsed: {parsed}")) + } + _ => Err(format!("Unknown operation: {operation}").into()), + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use error_backend::*; + use error_server::*; + use pulseengine_mcp_server::McpBackend; + + #[test] + fn test_error_types_exist() { + let _backend_error = ErrorBackendError::Internal("test".to_string()); + let _server_error = ErrorServerError::Transport("test".to_string()); + let _custom_error = CustomError::Network; + } + + #[test] + fn test_error_conversion() { + let custom_error = CustomError::Custom("test".to_string()); + let backend_error = ErrorBackendError::Internal(custom_error.to_string()); + + // Test that errors can be converted to protocol errors + let _protocol_error: pulseengine_mcp_protocol::Error = backend_error.into(); + } + + #[tokio::test] + async fn test_successful_tools() { + let backend = ErrorBackend::with_defaults(); + + let success_result = backend.success_tool("test".to_string()).await; + assert_eq!(success_result, "Success: test"); + + let validation_result = backend.validation_tool("valid_name".to_string()).await; + assert!(validation_result.is_ok()); + assert_eq!(validation_result.unwrap(), "Valid name: valid_name"); + } + + #[tokio::test] + async fn test_error_tools() { + let backend = ErrorBackend::with_defaults(); + + let error_result = backend.error_tool("test".to_string()).await; + assert!(error_result.is_err()); + assert_eq!( + error_result.unwrap_err().to_string(), + "Custom error: This tool always fails" + ); + + let io_error_result = backend.io_error_tool("test".to_string()).await; + assert!(io_error_result.is_err()); + assert_eq!( + io_error_result.unwrap_err().kind(), + std::io::ErrorKind::NotFound + ); + + let validation_error_result = backend.validation_tool("".to_string()).await; + assert!(validation_error_result.is_err()); + if let CustomError::Validation { field } = validation_error_result.unwrap_err() { + assert_eq!(field, "name"); + } else { + panic!("Expected validation error"); + } + } + + #[tokio::test] + async fn test_resource_errors() { + let server = ErrorServer::with_defaults(); + + let success_result = server.error_resource("success".to_string()).await; + assert!(success_result.is_ok()); + assert_eq!(success_result.unwrap(), "Resource data"); + + let not_found_result = server.error_resource("not_found".to_string()).await; + assert!(not_found_result.is_err()); + assert_eq!( + not_found_result.unwrap_err().kind(), + std::io::ErrorKind::NotFound + ); + + let permission_result = server.error_resource("permission".to_string()).await; + assert!(permission_result.is_err()); + assert_eq!( + permission_result.unwrap_err().kind(), + std::io::ErrorKind::PermissionDenied + ); + + let invalid_result = server.error_resource("invalid".to_string()).await; + assert!(invalid_result.is_err()); + assert_eq!( + invalid_result.unwrap_err().kind(), + std::io::ErrorKind::InvalidData + ); + } + + #[tokio::test] + async fn test_prompt_errors() { + let server = ErrorServer::with_defaults(); + + let success_result = server.error_prompt("success".to_string()).await; + assert!(success_result.is_ok()); + + let invalid_result = server.error_prompt("invalid".to_string()).await; + assert!(invalid_result.is_err()); + assert_eq!( + invalid_result.unwrap_err().kind(), + std::io::ErrorKind::InvalidInput + ); + + let unknown_result = server.error_prompt("unknown".to_string()).await; + assert!(unknown_result.is_err()); + assert_eq!( + unknown_result.unwrap_err().kind(), + std::io::ErrorKind::Other + ); + } + + #[tokio::test] + async fn test_complex_error_tool() { + let server = ErrorServer::with_defaults(); + + let divide_success = server.complex_error_tool("divide".to_string(), 10).await; + assert!(divide_success.is_ok()); + assert_eq!(divide_success.unwrap(), "Result: 10"); + + let divide_error = server.complex_error_tool("divide".to_string(), 0).await; + assert!(divide_error.is_err()); + assert_eq!(divide_error.unwrap_err().to_string(), "Division by zero"); + + let parse_success = server.complex_error_tool("parse".to_string(), 42).await; + assert!(parse_success.is_ok()); + assert_eq!(parse_success.unwrap(), "Parsed: 42"); + + let unknown_operation = server.complex_error_tool("unknown".to_string(), 1).await; + assert!(unknown_operation.is_err()); + assert_eq!( + unknown_operation.unwrap_err().to_string(), + "Unknown operation: unknown" + ); + } + + #[tokio::test] + async fn test_backend_error_propagation() { + let backend = ErrorBackend::with_defaults(); + + // Test that server info works + let info = backend.get_server_info(); + assert_eq!(info.server_info.name, "Error Backend"); + } + + #[test] + fn test_error_debug_formatting() { + let custom_error = CustomError::Custom("test error".to_string()); + let backend_error = ErrorBackendError::Internal("internal error".to_string()); + let server_error = ErrorServerError::InvalidParameter("param error".to_string()); + + // Test that errors format properly + assert!(format!("{custom_error:?}").contains("Custom")); + assert!(format!("{backend_error:?}").contains("Internal")); + assert!(format!("{server_error:?}").contains("InvalidParameter")); + + // Test display formatting + assert_eq!(custom_error.to_string(), "Custom error: test error"); + assert_eq!(backend_error.to_string(), "Internal error: internal error"); + assert_eq!(server_error.to_string(), "Invalid parameter: param error"); + } +} diff --git a/mcp-macros/tests/integration_full_tests.rs b/mcp-macros/tests/integration_full_tests.rs new file mode 100644 index 00000000..1588c7f3 --- /dev/null +++ b/mcp-macros/tests/integration_full_tests.rs @@ -0,0 +1,250 @@ +//! Full integration tests combining all macro features + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; +use serde_json::json; + +mod full_integration { + use super::*; + + /// A comprehensive server that demonstrates all macro features working together + #[mcp_server( + name = "Full Integration Test Server", + app_name = "integration-test", + version = "1.0.0", + description = "A server demonstrating all macro capabilities" + )] + #[derive(Clone)] + pub struct FullIntegrationServer { + data_store: + std::sync::Arc>>, + counter: std::sync::Arc, + } + + impl Default for FullIntegrationServer { + fn default() -> Self { + let mut store = std::collections::HashMap::new(); + store.insert( + "config".to_string(), + json!({"theme": "dark", "language": "en"}), + ); + store.insert( + "user_1".to_string(), + json!({"name": "Alice", "role": "admin"}), + ); + store.insert("user_2".to_string(), json!({"name": "Bob", "role": "user"})); + + Self { + data_store: std::sync::Arc::new(std::sync::RwLock::new(store)), + counter: std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0)), + } + } + } + + #[mcp_tools] + impl FullIntegrationServer { + /// Simple synchronous tool + pub fn get_server_status(&self) -> String { + "Server is running".to_string() + } + + /// Simple asynchronous tool + pub async fn increment_counter(&self) -> u64 { + self.counter + .fetch_add(1, std::sync::atomic::Ordering::SeqCst) + + 1 + } + + /// Data processing tool + pub async fn process_data( + &self, + input: serde_json::Value, + operation: String, + ) -> Result { + match operation.as_str() { + "validate" => { + if input.is_object() { + Ok(json!({"status": "valid", "data": input})) + } else { + Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Input must be an object", + )) + } + } + "count" => { + let count = self.counter.load(std::sync::atomic::Ordering::SeqCst); + Ok(json!({"count": count, "input": input})) + } + _ => Ok(json!({"operation": operation, "input": input})), + } + } + + /// Search data tool + #[allow(dead_code)] + pub async fn search_data( + &self, + query: String, + limit: Option, + _include_metadata: Option, + ) -> Result, std::io::Error> { + let store = self.data_store.read().unwrap(); + let mut results = Vec::new(); + + for (_key, value) in store.iter() { + if value.to_string().contains(&query) { + results.push(value.clone()); + } + } + + if let Some(limit) = limit { + results.truncate(limit as usize); + } + + Ok(results) + } + + /// Basic data resource + pub async fn data_resource(&self, key: String) -> Result { + let store = self.data_store.read().unwrap(); + store.get(&key).map(|v| v.to_string()).ok_or_else(|| { + std::io::Error::new( + std::io::ErrorKind::NotFound, + format!("Key not found: {key}"), + ) + }) + } + + /// User profile resource + #[allow(dead_code)] + pub async fn read_resource(&self, uri: String) -> Result { + if uri.starts_with("user://") { + let user_id = uri.strip_prefix("user://").unwrap_or("unknown"); + let store = self.data_store.read().unwrap(); + let user_key = format!("user_{user_id}"); + + let user_data = store.get(&user_key).ok_or_else(|| { + std::io::Error::new(std::io::ErrorKind::NotFound, "User not found") + })?; + + Ok(user_data.to_string()) + } else { + Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Invalid URI format", + )) + } + } + + /// Risky operation that can fail + pub async fn risky_operation(&self, mode: String) -> Result { + match mode.as_str() { + "success" => Ok("Operation completed successfully".to_string()), + "fail" => Err(std::io::Error::other("Operation failed as requested")), + _ => Ok(format!("Unknown mode: {mode}")), + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use full_integration::*; + use pulseengine_mcp_server::McpBackend; + + #[test] + fn test_full_server_compiles_and_creates() { + let server = FullIntegrationServer::with_defaults(); + let info = server.get_server_info(); + assert_eq!(info.server_info.name, "Full Integration Test Server"); + assert_eq!(info.server_info.version, "1.0.0"); + } + + #[test] + fn test_server_configuration() { + let server = FullIntegrationServer::with_defaults(); + let info = server.get_server_info(); + + assert_eq!(info.server_info.name, "Full Integration Test Server"); + assert_eq!(info.server_info.version, "1.0.0"); + assert_eq!( + info.instructions, + Some("A server demonstrating all macro capabilities".to_string()) + ); + + // Test that all capabilities are enabled + assert!(info.capabilities.tools.is_some()); + assert!(info.capabilities.resources.is_some()); + assert!(info.capabilities.prompts.is_some()); + assert!(info.capabilities.logging.is_some()); + } + + #[tokio::test] + async fn test_basic_tool_functionality() { + let server = FullIntegrationServer::with_defaults(); + + let status = server.get_server_status(); + assert_eq!(status, "Server is running"); + + let count1 = server.increment_counter().await; + let count2 = server.increment_counter().await; + assert_eq!(count2, count1 + 1); + } + + #[tokio::test] + async fn test_data_processing() { + let server = FullIntegrationServer::with_defaults(); + + let valid_input = json!({"key": "value"}); + let result = server + .process_data(valid_input.clone(), "validate".to_string()) + .await; + assert!(result.is_ok()); + + let count_result = server + .process_data(json!("test"), "count".to_string()) + .await; + assert!(count_result.is_ok()); + } + + #[tokio::test] + async fn test_resource_access() { + let server = FullIntegrationServer::with_defaults(); + + let config_result = server.data_resource("config".to_string()).await; + assert!(config_result.is_ok()); + assert!(config_result.unwrap().contains("dark")); + + let missing_result = server.data_resource("nonexistent".to_string()).await; + assert!(missing_result.is_err()); + assert_eq!( + missing_result.unwrap_err().kind(), + std::io::ErrorKind::NotFound + ); + } + + #[tokio::test] + async fn test_error_handling() { + let server = FullIntegrationServer::with_defaults(); + + let success_result = server.risky_operation("success".to_string()).await; + assert!(success_result.is_ok()); + + let fail_result = server.risky_operation("fail".to_string()).await; + assert!(fail_result.is_err()); + } + + #[test] + fn test_clone_and_send_sync() { + let server = FullIntegrationServer::with_defaults(); + let cloned = server.clone(); + + // Test that server can be cloned and shared across threads + let handle = std::thread::spawn(move || { + let _server = cloned; + "success" + }); + + assert_eq!(handle.join().unwrap(), "success"); + } +} diff --git a/mcp-macros/tests/integration_tests.rs b/mcp-macros/tests/integration_tests.rs index 0e806c49..fb5e85f5 100644 --- a/mcp-macros/tests/integration_tests.rs +++ b/mcp-macros/tests/integration_tests.rs @@ -8,8 +8,8 @@ use pulseengine_mcp_macros::{mcp_server, mcp_tools}; use pulseengine_mcp_protocol::McpResult; use std::sync::{ - atomic::{AtomicU64, Ordering}, Arc, + atomic::{AtomicU64, Ordering}, }; /// Test basic integration of server and tools macros @@ -223,9 +223,9 @@ fn test_server_capabilities_detection() { let logging_cap = info.capabilities.logging.unwrap(); assert_eq!(logging_cap.level, Some("info".to_string())); - // Should not have resources/prompts by default - assert!(info.capabilities.resources.is_none()); - assert!(info.capabilities.prompts.is_none()); + // Should have resources/prompts capabilities set by default + assert!(info.capabilities.resources.is_some()); + assert!(info.capabilities.prompts.is_some()); } /// Test version handling and configuration diff --git a/mcp-macros/tests/macro_attribute_tests.rs b/mcp-macros/tests/macro_attribute_tests.rs new file mode 100644 index 00000000..964a24d6 --- /dev/null +++ b/mcp-macros/tests/macro_attribute_tests.rs @@ -0,0 +1,299 @@ +//! Tests for macro attribute parsing and validation + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +mod minimal_server { + use super::*; + + #[mcp_server(name = "Minimal Server")] + #[derive(Default, Clone)] + pub struct MinimalServer; + + #[mcp_tools] + impl MinimalServer { + /// A minimal tool + pub async fn minimal_tool(&self) -> String { + "minimal".to_string() + } + } +} + +mod full_server { + use super::*; + + #[mcp_server( + name = "Full Server", + app_name = "test-app-macro-attribute-tests", + version = "1.0.0", + description = "A server with all attributes", + transport = "http" + )] + #[derive(Default, Clone)] + pub struct FullServer; + + #[mcp_tools] + #[allow(dead_code)] + impl FullServer { + /// A tool with all attributes + pub async fn full_tool(&self, input: String, optional: Option) -> String { + format!("Input: {input}, Optional: {optional:?}") + } + + /// A simple resource + pub async fn simple_resource(&self, id: String) -> Result { + Ok(format!("Resource: {id}")) + } + + /// A complex resource with all attributes + pub async fn complex_resource( + &self, + database: String, + table: String, + ) -> Result { + Ok(serde_json::json!({ + "database": database, + "table": table + })) + } + + /// A simple prompt + pub async fn simple_prompt( + &self, + topic: String, + ) -> Result { + Ok(pulseengine_mcp_protocol::PromptMessage { + role: pulseengine_mcp_protocol::PromptMessageRole::User, + content: pulseengine_mcp_protocol::PromptMessageContent::Text { + text: format!("Tell me about: {topic}"), + }, + }) + } + + /// A complex prompt with all attributes + pub async fn complex_prompt( + &self, + context: String, + style: String, + length: String, + ) -> Result { + Ok(pulseengine_mcp_protocol::PromptMessage { + role: pulseengine_mcp_protocol::PromptMessageRole::Assistant, + content: pulseengine_mcp_protocol::PromptMessageContent::Text { + text: format!("Generate {length} content about {context} in {style} style"), + }, + }) + } + } +} + +mod doc_comment_handling { + use super::*; + + /// This is a documented server + /// with multiple lines of documentation + /// that should be used as the description + #[mcp_server(name = "Documented Server")] + #[derive(Default, Clone)] + pub struct DocumentedServer; + + #[mcp_tools] + impl DocumentedServer { + /// This tool has documentation + /// across multiple lines + /// with detailed information + pub async fn documented_tool(&self, param: String) -> String { + format!("Documented: {param}") + } + + /// This resource reads documentation + /// from various sections + pub async fn documented_resource(&self, section: String) -> Result { + Ok(format!("Documentation for: {section}")) + } + + /// This prompt generates documentation + /// based on the provided input + pub async fn documented_prompt( + &self, + input: String, + ) -> Result { + Ok(pulseengine_mcp_protocol::PromptMessage { + role: pulseengine_mcp_protocol::PromptMessageRole::User, + content: pulseengine_mcp_protocol::PromptMessageContent::Text { + text: format!("Generate documentation for: {input}"), + }, + }) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use doc_comment_handling::*; + use full_server::*; + use minimal_server::*; + use pulseengine_mcp_server::McpBackend; + + #[test] + fn test_minimal_configurations() { + let _minimal_server = MinimalServer::with_defaults(); + } + + #[test] + fn test_full_configurations() { + let _full_server = FullServer::with_defaults(); + } + + #[test] + fn test_documented_configurations() { + let _doc_server = DocumentedServer::with_defaults(); + } + + #[test] + fn test_server_info_attributes() { + let minimal = MinimalServer::with_defaults(); + let full = FullServer::with_defaults(); + let documented = DocumentedServer::with_defaults(); + + let minimal_info = minimal.get_server_info(); + let full_info = full.get_server_info(); + let doc_info = documented.get_server_info(); + + // Test names + assert_eq!(minimal_info.server_info.name, "Minimal Server"); + assert_eq!(full_info.server_info.name, "Full Server"); + assert_eq!(doc_info.server_info.name, "Documented Server"); + + // Test versions + assert_eq!(full_info.server_info.version, "1.0.0"); + + // Test descriptions + assert_eq!( + full_info.instructions, + Some("A server with all attributes".to_string()) + ); + assert!(doc_info.instructions.is_some()); + assert!(doc_info.instructions.unwrap().contains("documented server")); + } + + #[test] + fn test_server_compilation() { + let minimal = MinimalServer::with_defaults(); + let full = FullServer::with_defaults(); + let documented = DocumentedServer::with_defaults(); + + let minimal_info = minimal.get_server_info(); + let full_info = full.get_server_info(); + let doc_info = documented.get_server_info(); + + // Test names + assert_eq!(minimal_info.server_info.name, "Minimal Server"); + assert_eq!(full_info.server_info.name, "Full Server"); + assert_eq!(doc_info.server_info.name, "Documented Server"); + } + + #[test] + fn test_config_types_exist() { + let _minimal_config = MinimalServerConfig::default(); + let _full_config = FullServerConfig::default(); + let _doc_config = DocumentedServerConfig::default(); + + // Test that configs have the right values + let full_config = FullServerConfig::default(); + assert_eq!(full_config.server_name, "Full Server"); + assert_eq!(full_config.server_version, "1.0.0"); + assert_eq!( + full_config.server_description, + Some("A server with all attributes".to_string()) + ); + } + + #[test] + fn test_error_types_exist() { + let _minimal_error = MinimalServerError::Internal("test".to_string()); + let _full_error = FullServerError::Transport("test".to_string()); + let _doc_error = DocumentedServerError::InvalidParameter("test".to_string()); + } + + #[tokio::test] + async fn test_tool_functionality() { + let server = MinimalServer::with_defaults(); + let minimal_result = server.minimal_tool().await; + assert_eq!(minimal_result, "minimal"); + } + + #[tokio::test] + async fn test_resource_functionality() { + let server = FullServer::with_defaults(); + + let simple_result = server.simple_resource("123".to_string()).await; + assert!(simple_result.is_ok()); + assert_eq!(simple_result.unwrap(), "Resource: 123"); + + let complex_result = server + .complex_resource("testdb".to_string(), "users".to_string()) + .await; + assert!(complex_result.is_ok()); + let json_value = complex_result.unwrap(); + assert_eq!(json_value["database"], "testdb"); + assert_eq!(json_value["table"], "users"); + } + + #[tokio::test] + async fn test_prompt_functionality() { + let server = FullServer::with_defaults(); + + let simple_result = server.simple_prompt("AI".to_string()).await; + assert!(simple_result.is_ok()); + + let complex_result = server + .complex_prompt( + "machine learning".to_string(), + "academic".to_string(), + "detailed".to_string(), + ) + .await; + assert!(complex_result.is_ok()); + } + + #[tokio::test] + async fn test_documented_functionality() { + let server = DocumentedServer::with_defaults(); + + let tool_result = server.documented_tool("test".to_string()).await; + assert_eq!(tool_result, "Documented: test"); + + let resource_result = server + .documented_resource("getting-started".to_string()) + .await; + assert!(resource_result.is_ok()); + assert_eq!( + resource_result.unwrap(), + "Documentation for: getting-started" + ); + + let prompt_result = server.documented_prompt("API usage".to_string()).await; + assert!(prompt_result.is_ok()); + } + + #[test] + fn test_capabilities_configuration() { + let minimal = MinimalServer::with_defaults(); + let full = FullServer::with_defaults(); + + let minimal_info = minimal.get_server_info(); + let full_info = full.get_server_info(); + + // All servers should have the same capabilities enabled + assert!(minimal_info.capabilities.tools.is_some()); + assert!(minimal_info.capabilities.resources.is_some()); + assert!(minimal_info.capabilities.prompts.is_some()); + assert!(minimal_info.capabilities.logging.is_some()); + + assert!(full_info.capabilities.tools.is_some()); + assert!(full_info.capabilities.resources.is_some()); + assert!(full_info.capabilities.prompts.is_some()); + assert!(full_info.capabilities.logging.is_some()); + } +} diff --git a/mcp-macros/tests/macro_tests.rs b/mcp-macros/tests/macro_tests.rs index 4285b10a..b9aa143e 100644 --- a/mcp-macros/tests/macro_tests.rs +++ b/mcp-macros/tests/macro_tests.rs @@ -6,8 +6,8 @@ use pulseengine_mcp_macros::mcp_server; use pulseengine_mcp_protocol::{ListToolsResult, PaginatedRequestParam}; use std::sync::{ - atomic::{AtomicU64, Ordering}, Arc, + atomic::{AtomicU64, Ordering}, }; /// Test basic mcp_server macro functionality @@ -160,9 +160,9 @@ fn test_server_capabilities() { let logging_cap = server_info.capabilities.logging.unwrap(); assert_eq!(logging_cap.level, Some("info".to_string())); - // Should not have resources/prompts by default - assert!(server_info.capabilities.resources.is_none()); - assert!(server_info.capabilities.prompts.is_none()); + // Should have resources/prompts capabilities set (even if not actively used) + assert!(server_info.capabilities.resources.is_some()); + assert!(server_info.capabilities.prompts.is_some()); } /// Test version handling diff --git a/mcp-macros/tests/macro_validation_tests.rs b/mcp-macros/tests/macro_validation_tests.rs new file mode 100644 index 00000000..59cd40a2 --- /dev/null +++ b/mcp-macros/tests/macro_validation_tests.rs @@ -0,0 +1,90 @@ +//! Validation tests that check macros generate correct code without calling private methods + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +#[test] +fn test_mcp_server_macro_compiles() { + #[mcp_server(name = "Test Server")] + #[derive(Clone, Default)] + struct TestServer; + + let _server = TestServer::with_defaults(); +} + +#[test] +fn test_mcp_tools_macro_compiles() { + #[mcp_server(name = "Tools Test Server")] + #[derive(Clone, Default)] + struct ToolsServer; + + #[mcp_tools] + impl ToolsServer { + #[allow(dead_code)] + async fn test_tool(&self, input: String) -> String { + format!("Processed: {input}") + } + } + + let _server = ToolsServer::with_defaults(); +} + +#[test] +fn test_multiple_macros_together() { + #[mcp_server(name = "Combined Test Server")] + #[derive(Clone, Default)] + struct CombinedServer; + + #[mcp_tools] + impl CombinedServer { + #[allow(dead_code)] + async fn example_tool(&self, data: String) -> Result { + Ok(format!("Tool result: {data}")) + } + } + + let _server = CombinedServer::with_defaults(); +} + +#[test] +fn test_server_with_complex_types() { + use serde::{Deserialize, Serialize}; + + #[derive(Debug, Clone, Serialize, Deserialize)] + struct CustomData { + id: u64, + name: String, + active: bool, + } + + #[mcp_server(name = "Complex Types Server")] + #[derive(Clone, Default)] + struct ComplexServer; + + #[mcp_tools] + impl ComplexServer { + #[allow(dead_code)] + async fn process_data(&self, data: CustomData) -> Result { + Ok(data) + } + + #[allow(dead_code)] + async fn simple_greeting(&self, name: String) -> String { + format!("Hello, {name}!") + } + } + + let _server = ComplexServer::with_defaults(); +} + +#[test] +fn test_server_configuration_types() { + #[mcp_server(name = "Config Test", version = "1.0.0", description = "Test server")] + #[derive(Clone, Default)] + struct ConfigServer; + + let server = ConfigServer::with_defaults(); + let info = server.get_server_info(); + + assert_eq!(info.server_info.name, "Config Test"); + assert_eq!(info.server_info.version, "1.0.0"); +} diff --git a/mcp-macros/tests/mcp_prompt_tests.rs b/mcp-macros/tests/mcp_prompt_tests.rs new file mode 100644 index 00000000..9838378b --- /dev/null +++ b/mcp-macros/tests/mcp_prompt_tests.rs @@ -0,0 +1,139 @@ +//! Tests for prompt-related functionality with macro-generated code + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +mod basic_prompt { + use super::*; + + #[mcp_server(name = "Prompt Test Server")] + #[derive(Default, Clone)] + pub struct PromptServer; + + #[mcp_tools] + impl PromptServer { + /// Generate a code review prompt + pub async fn generate_code_review(&self, code: String, language: String) -> String { + format!("Please review this {language} code:\n\n{code}") + } + } +} + +mod complex_prompt { + use super::*; + + #[mcp_server(name = "Complex Prompt Server")] + #[derive(Default, Clone)] + pub struct ComplexPromptServer; + + #[mcp_tools] + impl ComplexPromptServer { + /// Generate SQL queries from natural language + pub async fn sql_helper( + &self, + description: String, + table_schema: String, + output_format: String, + ) -> String { + format!( + "Generate a {output_format} SQL query for: {description}\nUsing schema: {table_schema}\nOutput format: {output_format}" + ) + } + + /// Generate documentation prompts + pub async fn generate_docs( + &self, + topic: String, + detail_level: String, + audience: String, + ) -> String { + format!("Create {detail_level} documentation about {topic} for audience: {audience}") + } + } +} + +mod sync_prompt { + use super::*; + + #[mcp_server(name = "Sync Prompt Server")] + #[derive(Default, Clone)] + pub struct SyncPromptServer; + + #[mcp_tools] + impl SyncPromptServer { + /// Generate simple prompts synchronously + pub fn simple_prompt(&self, topic: String) -> String { + format!("Please provide information about: {topic}") + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use basic_prompt::*; + use complex_prompt::*; + use pulseengine_mcp_server::McpBackend; + use sync_prompt::*; + + #[test] + fn test_prompt_servers_compile() { + let basic_server = PromptServer::with_defaults(); + let complex_server = ComplexPromptServer::with_defaults(); + let sync_server = SyncPromptServer::with_defaults(); + + let basic_info = basic_server.get_server_info(); + let complex_info = complex_server.get_server_info(); + let sync_info = sync_server.get_server_info(); + + assert_eq!(basic_info.server_info.name, "Prompt Test Server"); + assert_eq!(complex_info.server_info.name, "Complex Prompt Server"); + assert_eq!(sync_info.server_info.name, "Sync Prompt Server"); + } + + #[tokio::test] + async fn test_basic_prompt_functionality() { + let server = PromptServer::with_defaults(); + + let result = server + .generate_code_review( + "fn main() { println!(\"Hello\"); }".to_string(), + "Rust".to_string(), + ) + .await; + + assert!(result.contains("Rust")); + assert!(result.contains("println!")); + } + + #[tokio::test] + async fn test_complex_prompt_functionality() { + let server = ComplexPromptServer::with_defaults(); + + let sql_result = server + .sql_helper( + "Get all users".to_string(), + "users(id, name, email)".to_string(), + "SELECT".to_string(), + ) + .await; + assert!(sql_result.contains("users")); + assert!(sql_result.contains("SELECT")); + + let docs_result = server + .generate_docs( + "API endpoints".to_string(), + "comprehensive".to_string(), + "developers".to_string(), + ) + .await; + assert!(docs_result.contains("API endpoints")); + assert!(docs_result.contains("developers")); + } + + #[test] + fn test_sync_prompt_functionality() { + let server = SyncPromptServer::with_defaults(); + let result = server.simple_prompt("artificial intelligence".to_string()); + assert!(result.contains("artificial intelligence")); + } +} diff --git a/mcp-macros/tests/mcp_resource_tests.rs b/mcp-macros/tests/mcp_resource_tests.rs new file mode 100644 index 00000000..a2f8215a --- /dev/null +++ b/mcp-macros/tests/mcp_resource_tests.rs @@ -0,0 +1,140 @@ +//! Tests for resource-related functionality with macro-generated code + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +mod basic_resource { + use super::*; + + #[mcp_server(name = "Resource Test Server")] + #[derive(Default, Clone)] + pub struct ResourceServer; + + #[mcp_tools] + impl ResourceServer { + /// Read a file from the filesystem + pub async fn read_file(&self, path: String) -> Result { + if path.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Path cannot be empty", + )); + } + Ok(format!("Content of file: {path}")) + } + } +} + +mod complex_resource { + use super::*; + + #[mcp_server(name = "Complex Resource Server")] + #[derive(Default, Clone)] + pub struct ComplexResourceServer; + + #[mcp_tools] + impl ComplexResourceServer { + /// Read database table contents + pub async fn read_database_table( + &self, + database: String, + table: String, + ) -> Result { + if database.is_empty() || table.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Database and table names cannot be empty", + )); + } + Ok(format!("Data from {database}.{table}")) + } + + /// Get API data from external service + pub async fn get_api_data( + &self, + endpoint: String, + version: String, + ) -> Result { + Ok(format!("API data from {endpoint} (version {version})")) + } + } +} + +mod sync_resource { + use super::*; + + #[mcp_server(name = "Sync Resource Server")] + #[derive(Default, Clone)] + pub struct SyncResourceServer; + + #[mcp_tools] + impl SyncResourceServer { + /// Get configuration synchronously + pub fn get_config(&self, key: String) -> String { + format!("Config value for: {key}") + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use basic_resource::*; + use complex_resource::*; + use pulseengine_mcp_server::McpBackend; + use sync_resource::*; + + #[test] + fn test_resource_servers_compile() { + let basic_server = ResourceServer::with_defaults(); + let complex_server = ComplexResourceServer::with_defaults(); + let sync_server = SyncResourceServer::with_defaults(); + + let basic_info = basic_server.get_server_info(); + let complex_info = complex_server.get_server_info(); + let sync_info = sync_server.get_server_info(); + + assert_eq!(basic_info.server_info.name, "Resource Test Server"); + assert_eq!(complex_info.server_info.name, "Complex Resource Server"); + assert_eq!(sync_info.server_info.name, "Sync Resource Server"); + } + + #[tokio::test] + async fn test_basic_resource_functionality() { + let server = ResourceServer::with_defaults(); + + // Test valid path + let result = server.read_file("test.txt".to_string()).await; + assert!(result.is_ok()); + assert!(result.unwrap().contains("test.txt")); + + // Test empty path + let result = server.read_file("".to_string()).await; + assert!(result.is_err()); + } + + #[tokio::test] + async fn test_complex_resource_functionality() { + let server = ComplexResourceServer::with_defaults(); + + // Test database table access + let result = server + .read_database_table("users".to_string(), "accounts".to_string()) + .await; + assert!(result.is_ok()); + assert!(result.unwrap().contains("users.accounts")); + + // Test API data access + let result = server + .get_api_data("https://api.example.com".to_string(), "v1".to_string()) + .await; + assert!(result.is_ok()); + assert!(result.unwrap().contains("api.example.com")); + } + + #[test] + fn test_sync_resource_functionality() { + let server = SyncResourceServer::with_defaults(); + let result = server.get_config("database_url".to_string()); + assert!(result.contains("database_url")); + } +} diff --git a/mcp-macros/tests/mcp_tool_tests.rs b/mcp-macros/tests/mcp_tool_tests.rs index 548fa982..795615e9 100644 --- a/mcp-macros/tests/mcp_tool_tests.rs +++ b/mcp-macros/tests/mcp_tool_tests.rs @@ -1,4 +1,4 @@ -//! Comprehensive tests for the #[mcp_tool] and #[mcp_tools] macros +//! Comprehensive tests for the #[mcp_tools] and #[mcp_tools] macros //! //! These tests verify that the procedural macros generate correct tool definitions //! and integrate properly with the MCP framework. @@ -64,7 +64,7 @@ fn test_mcp_tools_with_params() { _ => { return Err(pulseengine_mcp_protocol::Error::invalid_params( "Unknown operation", - )) + )); } }; diff --git a/mcp-macros/tests/parameter_validation_tests.rs b/mcp-macros/tests/parameter_validation_tests.rs new file mode 100644 index 00000000..9a45db0d --- /dev/null +++ b/mcp-macros/tests/parameter_validation_tests.rs @@ -0,0 +1,306 @@ +//! Tests for parameter validation and edge cases + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +mod parameter_types { + use super::*; + + #[mcp_server(name = "Parameter Test Server")] + #[derive(Default, Clone)] + pub struct ParameterServer; + + #[mcp_tools] + #[allow(dead_code)] + impl ParameterServer { + /// Tool with various primitive types + pub async fn primitive_types( + &self, + string_param: String, + int_param: i32, + uint_param: u64, + float_param: f64, + bool_param: bool, + ) -> String { + format!( + "String: {string_param}, Int: {int_param}, UInt: {uint_param}, Float: {float_param}, Bool: {bool_param}" + ) + } + + /// Tool with optional parameters + pub async fn optional_params( + &self, + required: String, + optional_string: Option, + optional_int: Option, + ) -> String { + format!("Required: {required}, OptStr: {optional_string:?}, OptInt: {optional_int:?}") + } + + /// Tool with collection parameters + pub async fn collection_params( + &self, + string_vec: Vec, + number_vec: Vec, + ) -> String { + format!("Strings: {string_vec:?}, Numbers: {number_vec:?}") + } + + /// Tool with JSON parameter + pub async fn json_param(&self, data: serde_json::Value) -> String { + format!("JSON data: {data}") + } + + /// Resource access with parameter validation + pub async fn access_resource( + &self, + resource_type: String, + resource_id: String, + ) -> Result { + if resource_type.is_empty() || resource_id.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Resource type and ID cannot be empty", + )); + } + Ok(format!("Resource: {resource_type}/{resource_id}")) + } + + /// Complex resource with multiple parameters + pub async fn complex_resource( + &self, + database: String, + schema: String, + table: String, + action: String, + ) -> Result { + if database.is_empty() || schema.is_empty() || table.is_empty() || action.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "All parameters must be provided", + )); + } + Ok(format!( + "Complex resource: {database}.{schema}.{table} action={action}" + )) + } + + /// Generate prompt with parameters + pub async fn generate_prompt(&self, context: String, query: String) -> String { + format!("Context: {context} | Query: {query}") + } + } +} + +mod edge_cases { + use super::*; + + #[mcp_server(name = "Edge Case Server")] + #[derive(Default, Clone)] + pub struct EdgeCaseServer; + + #[mcp_tools] + #[allow(dead_code)] + impl EdgeCaseServer { + /// Tool with very long parameter names + pub async fn very_long_parameter_names( + &self, + this_is_a_very_long_parameter_name_that_tests_edge_cases: String, + another_extremely_long_parameter_name_for_comprehensive_testing: String, + ) -> String { + format!( + "Long params: {this_is_a_very_long_parameter_name_that_tests_edge_cases} and {another_extremely_long_parameter_name_for_comprehensive_testing}" + ) + } + + /// Tool with many parameters + #[allow(clippy::too_many_arguments)] + pub async fn many_parameters( + &self, + p1: String, + p2: String, + p3: String, + p4: String, + p5: String, + p6: i32, + p7: i32, + p8: i32, + p9: i32, + p10: i32, + ) -> String { + format!("Many params: {p1},{p2},{p3},{p4},{p5},{p6},{p7},{p8},{p9},{p10}") + } + + /// Edge case resource access + pub async fn edge_resource(&self, param: String) -> Result { + if param.len() > 100 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Parameter too long", + )); + } + Ok(format!("Edge resource: {param}")) + } + } +} + +mod validation_server { + use super::*; + + #[mcp_server(name = "Validation Server")] + #[derive(Default, Clone)] + pub struct ValidationServer; + + #[mcp_tools] + #[allow(dead_code)] + impl ValidationServer { + /// Strict validation tool + pub async fn strict_validation( + &self, + email: String, + age: u32, + ) -> Result { + // Email validation + if !email.contains('@') { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Invalid email format", + )); + } + + // Age validation + if !(18..=120).contains(&age) { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Age must be between 18 and 120", + )); + } + + Ok(format!("Valid user: {email} (age {age})")) + } + + /// Numeric boundary testing + pub async fn numeric_boundaries( + &self, + min_int: i32, + max_int: i32, + small_float: f32, + large_float: f64, + ) -> String { + format!("Boundaries: int={min_int}-{max_int}, float={small_float}-{large_float}") + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use edge_cases::*; + use parameter_types::*; + use pulseengine_mcp_server::McpBackend; + use validation_server::*; + + #[test] + fn test_parameter_servers_compile() { + let param_server = ParameterServer::with_defaults(); + let edge_server = EdgeCaseServer::with_defaults(); + let validation_server = ValidationServer::with_defaults(); + + let param_info = param_server.get_server_info(); + let edge_info = edge_server.get_server_info(); + let validation_info = validation_server.get_server_info(); + + assert_eq!(param_info.server_info.name, "Parameter Test Server"); + assert_eq!(edge_info.server_info.name, "Edge Case Server"); + assert_eq!(validation_info.server_info.name, "Validation Server"); + } + + #[tokio::test] + async fn test_primitive_types() { + let server = ParameterServer::with_defaults(); + let result = server + .primitive_types("test".to_string(), 42, 100u64, std::f64::consts::PI, true) + .await; + + assert!(result.contains("test")); + assert!(result.contains("42")); + assert!(result.contains("100")); + assert!(result.contains("3.14")); + assert!(result.contains("true")); + } + + #[tokio::test] + async fn test_optional_parameters() { + let server = ParameterServer::with_defaults(); + + // With all parameters + let result = server + .optional_params( + "required".to_string(), + Some("optional".to_string()), + Some(123), + ) + .await; + assert!(result.contains("required")); + assert!(result.contains("optional")); + assert!(result.contains("123")); + + // With only required parameter + let result = server + .optional_params("required_only".to_string(), None, None) + .await; + assert!(result.contains("required_only")); + assert!(result.contains("None")); + } + + #[tokio::test] + async fn test_validation_functionality() { + let server = ValidationServer::with_defaults(); + + // Valid input + let result = server + .strict_validation("test@example.com".to_string(), 25) + .await; + assert!(result.is_ok()); + assert!(result.unwrap().contains("test@example.com")); + + // Invalid email + let result = server + .strict_validation("invalid_email".to_string(), 25) + .await; + assert!(result.is_err()); + + // Invalid age + let result = server + .strict_validation("test@example.com".to_string(), 15) + .await; + assert!(result.is_err()); + } + + #[tokio::test] + async fn test_edge_cases() { + let server = EdgeCaseServer::with_defaults(); + + let result = server + .very_long_parameter_names("test1".to_string(), "test2".to_string()) + .await; + assert!(result.contains("test1")); + assert!(result.contains("test2")); + + // Test many parameters + let result = server + .many_parameters( + "a".to_string(), + "b".to_string(), + "c".to_string(), + "d".to_string(), + "e".to_string(), + 1, + 2, + 3, + 4, + 5, + ) + .await; + assert!(result.contains("a,b,c,d,e,1,2,3,4,5")); + } +} diff --git a/mcp-macros/tests/performance_tests.rs b/mcp-macros/tests/performance_tests.rs new file mode 100644 index 00000000..5c871c77 --- /dev/null +++ b/mcp-macros/tests/performance_tests.rs @@ -0,0 +1,261 @@ +//! Performance and concurrency tests for macro-generated code + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; +use tokio::time::{Duration, Instant}; + +mod performance_server { + use super::*; + + #[mcp_server(name = "Performance Test Server")] + #[derive(Clone)] + pub struct PerformanceServer { + counter: Arc, + data: Arc>, + } + + impl Default for PerformanceServer { + fn default() -> Self { + let mut data = std::collections::HashMap::new(); + for i in 0..1000 { + data.insert(format!("key_{i}"), format!("value_{i}")); + } + + Self { + counter: Arc::new(AtomicU64::new(0)), + data: Arc::new(data), + } + } + } + + #[mcp_tools] + impl PerformanceServer { + /// Fast counter increment + pub async fn increment_counter(&self) -> u64 { + self.counter.fetch_add(1, Ordering::Relaxed) + } + + /// Get current counter value + pub async fn get_counter(&self) -> u64 { + self.counter.load(Ordering::Relaxed) + } + + /// Bulk data lookup operation + pub async fn bulk_lookup(&self, keys: Vec) -> Vec> { + let mut results = Vec::new(); + for key in keys { + results.push(self.data.get(&key).cloned()); + } + results + } + + /// Memory-intensive operation + pub async fn memory_intensive(&self, size: usize) -> String { + let _data: Vec = vec![42; size]; + let checksum = if size > 0 { + 42u64 * (size as u64 % 100) + } else { + 0 + }; + format!("Allocated {size} bytes, checksum: {checksum}") + } + + /// CPU-intensive operation + pub async fn cpu_intensive(&self, iterations: u64) -> u64 { + let mut result = 0u64; + for i in 0..iterations { + result = result.wrapping_add(i * i); + } + result + } + + /// Simulated I/O operation + pub async fn simulated_io(&self, duration_ms: u64) -> String { + tokio::time::sleep(Duration::from_millis(duration_ms)).await; + format!("IO operation completed after {duration_ms}ms") + } + + /// Concurrent data access + pub async fn concurrent_access(&self, operations: u32) -> Vec { + let mut results = Vec::new(); + for _ in 0..operations { + let value = self.counter.fetch_add(1, Ordering::Relaxed); + results.push(value); + } + results + } + + /// Performance resource access + pub async fn performance_resource( + &self, + resource_type: String, + resource_id: String, + ) -> Result { + if resource_type.is_empty() || resource_id.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Resource type and ID cannot be empty", + )); + } + + // Simulate performance tracking + let start = Instant::now(); + tokio::time::sleep(Duration::from_millis(1)).await; + let elapsed = start.elapsed(); + + Ok(format!( + "Resource {resource_type}/{resource_id} accessed in {elapsed:?}" + )) + } + + /// Generate performance prompt + pub async fn performance_prompt( + &self, + query: String, + optimization_level: String, + ) -> String { + format!( + "Performance analysis for '{query}' with optimization level: {optimization_level}" + ) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use performance_server::*; + use pulseengine_mcp_server::McpBackend; + + #[test] + fn test_performance_server_compiles() { + let server = PerformanceServer::with_defaults(); + let info = server.get_server_info(); + assert_eq!(info.server_info.name, "Performance Test Server"); + } + + #[tokio::test] + async fn test_counter_operations() { + let server = PerformanceServer::with_defaults(); + + // Test increment + let initial = server.increment_counter().await; + let next = server.increment_counter().await; + assert_eq!(next, initial + 1); + + // Test get counter + let current = server.get_counter().await; + assert!(current >= 2); + } + + #[tokio::test] + async fn test_bulk_operations() { + let server = PerformanceServer::with_defaults(); + + let keys = vec![ + "key_1".to_string(), + "key_2".to_string(), + "key_999".to_string(), + "nonexistent".to_string(), + ]; + let results = server.bulk_lookup(keys).await; + + assert_eq!(results.len(), 4); + assert_eq!(results[0], Some("value_1".to_string())); + assert_eq!(results[1], Some("value_2".to_string())); + assert_eq!(results[2], Some("value_999".to_string())); + assert_eq!(results[3], None); + } + + #[tokio::test] + async fn test_intensive_operations() { + let server = PerformanceServer::with_defaults(); + + // Test memory intensive + let memory_result = server.memory_intensive(1000).await; + assert!(memory_result.contains("1000 bytes")); + + // Test CPU intensive + let cpu_result = server.cpu_intensive(100).await; + assert!(cpu_result > 0); + } + + #[tokio::test] + async fn test_io_simulation() { + let server = PerformanceServer::with_defaults(); + + let start = Instant::now(); + let result = server.simulated_io(50).await; + let elapsed = start.elapsed(); + + assert!(result.contains("50ms")); + assert!(elapsed >= Duration::from_millis(45)); // Allow some tolerance + } + + #[tokio::test] + async fn test_concurrent_access() { + let server = PerformanceServer::with_defaults(); + + let results = server.concurrent_access(10).await; + assert_eq!(results.len(), 10); + + // Results should be sequential (each increment returns the previous value) + for i in 1..results.len() { + assert_eq!(results[i], results[i - 1] + 1); + } + } + + #[tokio::test] + async fn test_performance_resource() { + let server = PerformanceServer::with_defaults(); + + let result = server + .performance_resource("cache".to_string(), "item_1".to_string()) + .await; + assert!(result.is_ok()); + assert!(result.unwrap().contains("cache/item_1")); + + // Test error case + let result = server + .performance_resource("".to_string(), "item_1".to_string()) + .await; + assert!(result.is_err()); + } + + #[tokio::test] + async fn test_performance_prompt() { + let server = PerformanceServer::with_defaults(); + + let result = server + .performance_prompt("database query".to_string(), "O3".to_string()) + .await; + assert!(result.contains("database query")); + assert!(result.contains("O3")); + } + + #[tokio::test] + async fn test_high_concurrency() { + let server = Arc::new(PerformanceServer::with_defaults()); + let mut handles = Vec::new(); + + // Spawn multiple concurrent tasks + for _ in 0..20 { + let server_clone = Arc::clone(&server); + let handle = tokio::spawn(async move { server_clone.increment_counter().await }); + handles.push(handle); + } + + // Wait for all tasks to complete + let mut results = Vec::new(); + for handle in handles { + results.push(handle.await.unwrap()); + } + + assert_eq!(results.len(), 20); + + // Final counter should be at least 20 + let final_count = server.get_counter().await; + assert!(final_count >= 20); + } +} diff --git a/mcp-macros/tests/security_tests.rs b/mcp-macros/tests/security_tests.rs new file mode 100644 index 00000000..0ea0227c --- /dev/null +++ b/mcp-macros/tests/security_tests.rs @@ -0,0 +1,323 @@ +//! Security-focused tests for macro-generated code + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; + +mod security_server { + use super::*; + + #[mcp_server( + name = "Security Test Server", + app_name = "security-test-security-tests" + )] + #[derive(Default, Clone)] + pub struct SecurityServer; + + #[mcp_tools] + #[allow(dead_code)] + impl SecurityServer { + /// Validate and sanitize user input + pub async fn sanitize_input(&self, input: String) -> Result { + // Check for common injection patterns + let dangerous_patterns = [ + "';", + "script>", + "(); + + Ok(sanitized) + } + + /// Validate email addresses with security checks + pub async fn validate_email(&self, email: String) -> Result { + // Basic email validation + if !email.contains('@') || email.split('@').count() != 2 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Invalid email format", + )); + } + + let parts: Vec<&str> = email.split('@').collect(); + let (local, domain) = (parts[0], parts[1]); + + // Security checks + if local.is_empty() || domain.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Empty email parts", + )); + } + + if local.len() > 64 || domain.len() > 255 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Email parts too long", + )); + } + + // Check for suspicious patterns + let suspicious_patterns = ["admin@", "root@", "system@", "postmaster@"]; + for pattern in &suspicious_patterns { + if email.to_lowercase().starts_with(pattern) { + return Err(std::io::Error::new( + std::io::ErrorKind::PermissionDenied, + "Restricted email address", + )); + } + } + + Ok(email.to_lowercase()) + } + + /// Rate-limited operation + pub async fn rate_limited_operation( + &self, + operation_id: String, + ) -> Result { + // Simulate rate limiting + if operation_id.is_empty() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Operation ID cannot be empty", + )); + } + + Ok(format!("Operation {operation_id} executed")) + } + + /// Validate file paths to prevent directory traversal + pub async fn validate_file_path(&self, path: String) -> Result { + // Check for directory traversal attempts + if path.contains("..") || path.contains("~") { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Directory traversal detected", + )); + } + + // Check for absolute paths + if path.starts_with('/') || path.contains(':') { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Absolute paths not allowed", + )); + } + + Ok(path) + } + + /// Validate password strength + pub async fn validate_password(&self, password: String) -> Result { + if password.len() < 8 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Password too short", + )); + } + + let has_upper = password.chars().any(|c| c.is_uppercase()); + let has_lower = password.chars().any(|c| c.is_lowercase()); + let has_digit = password.chars().any(|c| c.is_numeric()); + let has_special = password.chars().any(|c| "!@#$%^&*()".contains(c)); + + if !has_upper || !has_lower || !has_digit || !has_special { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Password does not meet complexity requirements", + )); + } + + Ok("Password meets security requirements".to_string()) + } + + /// Secure resource access with validation + pub async fn secure_resource( + &self, + resource_type: String, + resource_id: String, + ) -> Result { + // Validate resource type + let allowed_types = ["user", "document", "config", "log"]; + if !allowed_types.contains(&resource_type.as_str()) { + return Err(std::io::Error::new( + std::io::ErrorKind::PermissionDenied, + "Resource type not allowed", + )); + } + + // Validate resource ID format + if !resource_id + .chars() + .all(|c| c.is_alphanumeric() || c == '-' || c == '_') + { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Invalid resource ID format", + )); + } + + if resource_id.len() > 50 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Resource ID too long", + )); + } + + // Simulate access control check + match resource_type.as_str() { + "user" => { + // Users can only access their own resources + if resource_id.starts_with("admin_") || resource_id.starts_with("system_") { + return Err(std::io::Error::new( + std::io::ErrorKind::PermissionDenied, + "Access denied to privileged resource", + )); + } + } + "config" => { + // Config access is restricted + return Err(std::io::Error::new( + std::io::ErrorKind::PermissionDenied, + "Configuration access requires elevated privileges", + )); + } + _ => {} // Other types allowed + } + + Ok(format!( + "Secure access to {resource_type} resource: {resource_id}" + )) + } + + /// Generate secure prompts with content filtering + pub async fn secure_prompt(&self, topic: String, context: String) -> String { + // Content filtering + let forbidden_topics = [ + "password", + "security", + "hack", + "exploit", + "vulnerability", + "inject", + "malware", + "virus", + "phishing", + "social engineering", + ]; + + for forbidden in &forbidden_topics { + if topic.to_lowercase().contains(forbidden) + || context.to_lowercase().contains(forbidden) + { + return format!("Error: Topic contains forbidden content: {forbidden}"); + } + } + + // Length validation + if topic.len() > 100 || context.len() > 500 { + return "Error: Input too long".to_string(); + } + + // Generate safe prompt + let safe_text = format!( + "Discuss the topic '{}' in the context of '{}'. Please keep the discussion professional and constructive.", + topic + .chars() + .filter(|c| c.is_alphanumeric() || " .-_".contains(*c)) + .collect::(), + context + .chars() + .filter(|c| c.is_alphanumeric() || " .-_".contains(*c)) + .collect::() + ); + + safe_text + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use pulseengine_mcp_server::McpBackend; + use security_server::*; + + #[test] + fn test_security_server_compiles() { + let _server = SecurityServer::with_defaults(); + } + + #[tokio::test] + async fn test_input_sanitization() { + let server = SecurityServer::with_defaults(); + + // Test safe input + let safe_result = server.sanitize_input("Hello World 123".to_string()).await; + assert!(safe_result.is_ok()); + assert_eq!(safe_result.unwrap(), "Hello World 123"); + } + + #[tokio::test] + async fn test_email_validation() { + let server = SecurityServer::with_defaults(); + + // Test valid email + let valid_result = server.validate_email("user@example.com".to_string()).await; + assert!(valid_result.is_ok()); + assert_eq!(valid_result.unwrap(), "user@example.com"); + + // Test invalid email + let invalid_result = server.validate_email("invalid-email".to_string()).await; + assert!(invalid_result.is_err()); + } + + #[tokio::test] + async fn test_password_validation() { + let server = SecurityServer::with_defaults(); + + // Test strong password + let strong_result = server.validate_password("MyP@ssw0rd123".to_string()).await; + assert!(strong_result.is_ok()); + + // Test weak password + let weak_result = server.validate_password("weak".to_string()).await; + assert!(weak_result.is_err()); + } + + #[tokio::test] + async fn test_server_info() { + let server = SecurityServer::with_defaults(); + let info = server.get_server_info(); + assert_eq!(info.server_info.name, "Security Test Server"); + } +} diff --git a/mcp-macros/tests/server_lifecycle_tests.rs b/mcp-macros/tests/server_lifecycle_tests.rs new file mode 100644 index 00000000..7560f12b --- /dev/null +++ b/mcp-macros/tests/server_lifecycle_tests.rs @@ -0,0 +1,236 @@ +//! Tests for server lifecycle management and fluent API + +use pulseengine_mcp_macros::mcp_server; + +mod lifecycle_server { + use super::*; + + #[mcp_server(name = "Lifecycle Test Server")] + #[derive(Default, Clone)] + pub struct LifecycleServer { + initialized: bool, + } + + impl LifecycleServer { + #[allow(dead_code)] + pub fn new_with_flag(flag: bool) -> Self { + Self { initialized: flag } + } + + pub fn is_initialized(&self) -> bool { + self.initialized + } + } +} + +mod app_specific_lifecycle { + use super::*; + + #[mcp_server( + name = "App Lifecycle Server", + app_name = "lifecycle-test-app-server-lifecycle-tests", + version = "1.2.3", + description = "Server for testing application-specific lifecycle" + )] + #[derive(Default, Clone)] + pub struct AppLifecycleServer { + app_data: std::collections::HashMap, + } + + impl AppLifecycleServer { + pub fn with_data(mut self, key: String, value: String) -> Self { + self.app_data.insert(key, value); + self + } + + pub fn get_data(&self, key: &str) -> Option<&String> { + self.app_data.get(key) + } + } +} + +mod transport_server { + use super::*; + + #[mcp_server(name = "Transport Server", transport = "http")] + #[derive(Default, Clone)] + pub struct TransportServer; +} + +#[cfg(test)] +mod tests { + use super::*; + use app_specific_lifecycle::*; + use lifecycle_server::*; + use pulseengine_mcp_server::McpBackend; + use transport_server::*; + + #[test] + fn test_server_creation() { + let server = LifecycleServer::with_defaults(); + assert!(!server.is_initialized()); // Default should be false via Default trait + } + + #[test] + fn test_server_with_custom_data() { + let server = AppLifecycleServer::with_defaults() + .with_data("key1".to_string(), "value1".to_string()) + .with_data("key2".to_string(), "value2".to_string()); + + assert_eq!(server.get_data("key1"), Some(&"value1".to_string())); + assert_eq!(server.get_data("key2"), Some(&"value2".to_string())); + assert_eq!(server.get_data("key3"), None); + } + + #[test] + fn test_config_types_generated() { + let _lifecycle_config = LifecycleServerConfig::default(); + let _app_config = AppLifecycleServerConfig::default(); + let _transport_config = TransportServerConfig::default(); + } + + #[test] + fn test_error_types_generated() { + let _lifecycle_error = LifecycleServerError::Internal("test".to_string()); + let _app_error = AppLifecycleServerError::Transport("test".to_string()); + let _transport_error = TransportServerError::InvalidParameter("test".to_string()); + } + + #[test] + fn test_service_types_generated() { + // These types should exist but can't be easily instantiated in tests + // due to async requirements. We just test they compile. + let _lifecycle_type: Option = None; + let _app_type: Option = None; + let _transport_type: Option = None; + } + + #[test] + fn test_server_info_configuration() { + let lifecycle_server = LifecycleServer::with_defaults(); + let app_server = AppLifecycleServer::with_defaults(); + let transport_server = TransportServer::with_defaults(); + + let lifecycle_info = lifecycle_server.get_server_info(); + let app_info = app_server.get_server_info(); + let transport_info = transport_server.get_server_info(); + + // Test names + assert_eq!(lifecycle_info.server_info.name, "Lifecycle Test Server"); + assert_eq!(app_info.server_info.name, "App Lifecycle Server"); + assert_eq!(transport_info.server_info.name, "Transport Server"); + + // Test version + assert_eq!(app_info.server_info.version, "1.2.3"); + + // Test description + assert_eq!( + app_info.instructions, + Some("Server for testing application-specific lifecycle".to_string()) + ); + assert_eq!(lifecycle_info.instructions, None); + } + + #[test] + fn test_capabilities_enabled() { + let server = LifecycleServer::with_defaults(); + let info = server.get_server_info(); + + // All capabilities should be enabled + assert!(info.capabilities.tools.is_some()); + assert!(info.capabilities.resources.is_some()); + assert!(info.capabilities.prompts.is_some()); + assert!(info.capabilities.logging.is_some()); + } + + #[tokio::test] + async fn test_health_check() { + let lifecycle_server = LifecycleServer::with_defaults(); + let app_server = AppLifecycleServer::with_defaults(); + let transport_server = TransportServer::with_defaults(); + + assert!(lifecycle_server.health_check().await.is_ok()); + assert!(app_server.health_check().await.is_ok()); + assert!(transport_server.health_check().await.is_ok()); + } + + #[tokio::test] + async fn test_backend_methods() { + let server = LifecycleServer::with_defaults(); + + // Test list operations return empty results + let tools = server + .list_tools(pulseengine_mcp_protocol::PaginatedRequestParam { cursor: None }) + .await + .unwrap(); + assert_eq!(tools.tools.len(), 0); + + let resources = server + .list_resources(pulseengine_mcp_protocol::PaginatedRequestParam { cursor: None }) + .await + .unwrap(); + assert_eq!(resources.resources.len(), 0); + + let prompts = server + .list_prompts(pulseengine_mcp_protocol::PaginatedRequestParam { cursor: None }) + .await + .unwrap(); + assert_eq!(prompts.prompts.len(), 0); + + // Test error cases + let tool_result = server + .call_tool(pulseengine_mcp_protocol::CallToolRequestParam { + name: "nonexistent".to_string(), + arguments: None, + }) + .await; + assert!(tool_result.is_err()); + + let resource_result = server + .read_resource(pulseengine_mcp_protocol::ReadResourceRequestParam { + uri: "nonexistent://resource".to_string(), + }) + .await; + assert!(resource_result.is_err()); + + let prompt_result = server + .get_prompt(pulseengine_mcp_protocol::GetPromptRequestParam { + name: "nonexistent".to_string(), + arguments: None, + }) + .await; + assert!(prompt_result.is_err()); + } + + #[test] + fn test_config_defaults() { + let config = LifecycleServerConfig::default(); + let app_config = AppLifecycleServerConfig::default(); + + assert_eq!(config.server_name, "Lifecycle Test Server"); + assert_eq!(app_config.server_name, "App Lifecycle Server"); + assert_eq!(app_config.server_version, "1.2.3"); + assert_eq!( + app_config.server_description, + Some("Server for testing application-specific lifecycle".to_string()) + ); + } + + #[test] + #[cfg(feature = "auth")] + fn test_auth_config_methods() { + // Test that auth config methods exist when auth feature is enabled + let _lifecycle_auth = LifecycleServerConfig::get_auth_config(); + let _app_auth = AppLifecycleServerConfig::get_auth_config(); + let _transport_auth = TransportServerConfig::get_auth_config(); + } + + #[tokio::test] + #[cfg(feature = "auth")] + async fn test_auth_manager_creation() { + // These will fail in test environment but should compile + let _lifecycle_result = LifecycleServer::create_auth_manager().await; + let _app_result = AppLifecycleServer::create_auth_manager().await; + let _transport_result = TransportServer::create_auth_manager().await; + } +} diff --git a/mcp-macros/tests/type_system_tests.rs b/mcp-macros/tests/type_system_tests.rs new file mode 100644 index 00000000..14616bcb --- /dev/null +++ b/mcp-macros/tests/type_system_tests.rs @@ -0,0 +1,754 @@ +//! Tests for type system integration and complex type handling + +use pulseengine_mcp_macros::{mcp_server, mcp_tools}; +use serde::{Deserialize, Serialize}; +use std::collections::HashMap; + +mod custom_types { + use super::*; + + #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] + pub struct User { + pub id: u64, + pub name: String, + pub email: String, + pub active: bool, + pub metadata: HashMap, + } + + #[derive(Debug, Clone, Serialize, Deserialize)] + pub struct CreateUserRequest { + pub name: String, + pub email: String, + pub initial_metadata: Option>, + } + + #[derive(Debug, Clone, Serialize, Deserialize)] + pub struct UpdateUserRequest { + pub name: Option, + pub email: Option, + pub active: Option, + pub metadata_updates: Option>, + } + + #[derive(Debug, Clone, Serialize, Deserialize)] + pub enum UserRole { + Admin, + Moderator, + User, + Guest, + } + + #[derive(Debug, Clone, Serialize, Deserialize)] + pub struct PaginationParams { + pub limit: Option, + pub offset: Option, + pub sort_by: Option, + pub order: Option, + } + + #[derive(Debug, Clone, Serialize, Deserialize)] + pub struct PaginatedResponse { + pub items: Vec, + pub total: u64, + pub limit: u32, + pub offset: u32, + } + + #[derive(Debug, thiserror::Error)] + pub enum UserError { + #[error("User not found: {id}")] + NotFound { id: u64 }, + #[error("Invalid email format: {email}")] + InvalidEmail { email: String }, + #[error("Duplicate user: {field}")] + Duplicate { field: String }, + #[error("Validation error: {message}")] + Validation { message: String }, + } +} + +mod type_system_server { + use super::*; + use custom_types::*; + + #[mcp_server(name = "Type System Test Server")] + #[derive(Clone)] + pub struct TypeSystemServer { + users: std::sync::Arc>>, + next_id: std::sync::Arc, + } + + impl Default for TypeSystemServer { + fn default() -> Self { + let mut users = HashMap::new(); + users.insert( + 1, + User { + id: 1, + name: "Alice".to_string(), + email: "alice@example.com".to_string(), + active: true, + metadata: [("role".to_string(), "admin".to_string())] + .into_iter() + .collect(), + }, + ); + users.insert( + 2, + User { + id: 2, + name: "Bob".to_string(), + email: "bob@example.com".to_string(), + active: true, + metadata: HashMap::new(), + }, + ); + + Self { + users: std::sync::Arc::new(std::sync::RwLock::new(users)), + next_id: std::sync::Arc::new(std::sync::atomic::AtomicU64::new(3)), + } + } + } + + #[mcp_tools] + #[allow(dead_code)] + impl TypeSystemServer { + /// Create a new user with complex type handling + pub async fn create_user(&self, request: CreateUserRequest) -> Result { + // Validate email format + if !request.email.contains('@') { + return Err(UserError::InvalidEmail { + email: request.email, + }); + } + + // Check for duplicates + let users = self.users.read().unwrap(); + for user in users.values() { + if user.email == request.email { + return Err(UserError::Duplicate { + field: "email".to_string(), + }); + } + if user.name == request.name { + return Err(UserError::Duplicate { + field: "name".to_string(), + }); + } + } + drop(users); + + // Create new user + let id = self + .next_id + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + let user = User { + id, + name: request.name, + email: request.email, + active: true, + metadata: request.initial_metadata.unwrap_or_default(), + }; + + // Store user + let mut users = self.users.write().unwrap(); + users.insert(id, user.clone()); + + Ok(user) + } + + /// Get user by ID with optional field selection + pub async fn get_user( + &self, + id: u64, + include_metadata: Option, + ) -> Result { + let users = self.users.read().unwrap(); + let mut user = users.get(&id).cloned().ok_or(UserError::NotFound { id })?; + + // Optionally exclude metadata + if !include_metadata.unwrap_or(true) { + user.metadata.clear(); + } + + Ok(user) + } + + /// Update user with partial update pattern + pub async fn update_user( + &self, + id: u64, + request: UpdateUserRequest, + ) -> Result { + let mut users = self.users.write().unwrap(); + let user = users.get_mut(&id).ok_or(UserError::NotFound { id })?; + + // Apply updates + if let Some(name) = request.name { + if name.is_empty() { + return Err(UserError::Validation { + message: "Name cannot be empty".to_string(), + }); + } + user.name = name; + } + + if let Some(email) = request.email { + if !email.contains('@') { + return Err(UserError::InvalidEmail { email }); + } + user.email = email; + } + + if let Some(active) = request.active { + user.active = active; + } + + if let Some(metadata_updates) = request.metadata_updates { + user.metadata.extend(metadata_updates); + } + + Ok(user.clone()) + } + + /// List users with pagination and complex return types + pub async fn list_users(&self, params: PaginationParams) -> PaginatedResponse { + let users = self.users.read().unwrap(); + let mut user_list: Vec = users.values().cloned().collect(); + + // Sort if requested + if let Some(sort_by) = ¶ms.sort_by { + match sort_by.as_str() { + "name" => user_list.sort_by(|a, b| a.name.cmp(&b.name)), + "email" => user_list.sort_by(|a, b| a.email.cmp(&b.email)), + "id" => user_list.sort_by(|a, b| a.id.cmp(&b.id)), + _ => {} // Invalid sort field, ignore + } + + // Apply order + if params.order.as_deref() == Some("desc") { + user_list.reverse(); + } + } + + let total = user_list.len() as u64; + let offset = params.offset.unwrap_or(0) as usize; + let limit = params.limit.unwrap_or(10) as usize; + + // Apply pagination + let items = user_list.into_iter().skip(offset).take(limit).collect(); + + PaginatedResponse { + items, + total, + limit: limit as u32, + offset: offset as u32, + } + } + + /// Delete user and return the deleted user + pub async fn delete_user(&self, id: u64) -> Result { + let mut users = self.users.write().unwrap(); + users.remove(&id).ok_or(UserError::NotFound { id }) + } + + /// Work with enums and complex matching + pub async fn set_user_role(&self, id: u64, role: UserRole) -> Result { + let mut users = self.users.write().unwrap(); + let user = users.get_mut(&id).ok_or(UserError::NotFound { id })?; + + let role_string = match role { + UserRole::Admin => "admin", + UserRole::Moderator => "moderator", + UserRole::User => "user", + UserRole::Guest => "guest", + }; + + user.metadata + .insert("role".to_string(), role_string.to_string()); + + Ok(format!("User {} role set to {}", user.name, role_string)) + } + + /// Generic type handling with vectors and maps + pub async fn batch_update_metadata( + &self, + updates: HashMap>, + ) -> Result, UserError> { + let mut users = self.users.write().unwrap(); + let mut updated_ids = Vec::new(); + + for (user_id, metadata_updates) in updates { + if let Some(user) = users.get_mut(&user_id) { + user.metadata.extend(metadata_updates); + updated_ids.push(user_id); + } + } + + Ok(updated_ids) + } + + /// Complex nested types with Options and Results + pub async fn search_users( + &self, + query: Option, + filters: Option>, + limit: Option, + ) -> Result, UserError> { + let users = self.users.read().unwrap(); + let mut results: Vec = users.values().cloned().collect(); + + // Apply query filter + if let Some(q) = query { + let query_lower = q.to_lowercase(); + results.retain(|user| { + user.name.to_lowercase().contains(&query_lower) + || user.email.to_lowercase().contains(&query_lower) + }); + } + + // Apply metadata filters + if let Some(filters) = filters { + results.retain(|user| { + filters.iter().all(|(key, value)| { + user.metadata.get(key).map(|v| v == value).unwrap_or(false) + }) + }); + } + + // Apply limit + if let Some(limit) = limit { + results.truncate(limit as usize); + } + + Ok(results) + } + + /// Resource with complex type serialization + pub async fn user_profile_resource( + &self, + id: String, + ) -> Result { + let user_id: u64 = id.parse().map_err(|_| { + std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid user ID") + })?; + + let users = self.users.read().unwrap(); + let user = users.get(&user_id).ok_or_else(|| { + std::io::Error::new(std::io::ErrorKind::NotFound, "User not found") + })?; + + // Serialize to JSON + serde_json::to_value(user).map_err(|e| std::io::Error::other(e.to_string())) + } + + /// Prompt with complex type handling in parameters + pub async fn user_prompt( + &self, + user_data: serde_json::Value, + template_type: String, + ) -> Result { + // Parse user data + let user: User = serde_json::from_value(user_data).map_err(|e| { + std::io::Error::new(std::io::ErrorKind::InvalidInput, e.to_string()) + })?; + + let prompt_text = match template_type.as_str() { + "welcome" => format!( + "Welcome {}! We're glad to have you at {}.", + user.name, user.email + ), + "profile" => format!( + "User Profile:\nName: {}\nEmail: {}\nActive: {}\nMetadata: {:?}", + user.name, user.email, user.active, user.metadata + ), + "admin" => { + if user.metadata.get("role") == Some(&"admin".to_string()) { + format!("Admin user {} has full system access.", user.name) + } else { + return Err(std::io::Error::new( + std::io::ErrorKind::PermissionDenied, + "Not an admin user", + )); + } + } + _ => { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "Unknown template type", + )); + } + }; + + Ok(pulseengine_mcp_protocol::PromptMessage { + role: pulseengine_mcp_protocol::PromptMessageRole::User, + content: pulseengine_mcp_protocol::PromptMessageContent::Text { text: prompt_text }, + }) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use custom_types::*; + use type_system_server::*; + + #[test] + fn test_custom_types_serialize() { + let user = User { + id: 1, + name: "Test".to_string(), + email: "test@example.com".to_string(), + active: true, + metadata: [("key".to_string(), "value".to_string())] + .into_iter() + .collect(), + }; + + let json = serde_json::to_string(&user).unwrap(); + let deserialized: User = serde_json::from_str(&json).unwrap(); + assert_eq!(user, deserialized); + } + + #[test] + fn test_server_compiles() { + let _server = TypeSystemServer::with_defaults(); + } + + #[tokio::test] + async fn test_create_user() { + let server = TypeSystemServer::with_defaults(); + + let request = CreateUserRequest { + name: "Charlie".to_string(), + email: "charlie@example.com".to_string(), + initial_metadata: Some( + [("department".to_string(), "engineering".to_string())] + .into_iter() + .collect(), + ), + }; + + let result = server.create_user(request).await; + assert!(result.is_ok()); + + let user = result.unwrap(); + assert_eq!(user.name, "Charlie"); + assert_eq!(user.email, "charlie@example.com"); + assert_eq!( + user.metadata.get("department"), + Some(&"engineering".to_string()) + ); + assert!(user.active); + } + + #[tokio::test] + async fn test_create_user_validation() { + let server = TypeSystemServer::with_defaults(); + + // Test invalid email + let invalid_email_request = CreateUserRequest { + name: "Invalid".to_string(), + email: "not-an-email".to_string(), + initial_metadata: None, + }; + + let result = server.create_user(invalid_email_request).await; + assert!(result.is_err()); + match result.unwrap_err() { + UserError::InvalidEmail { email } => assert_eq!(email, "not-an-email"), + _ => panic!("Expected InvalidEmail error"), + } + + // Test duplicate email + let duplicate_request = CreateUserRequest { + name: "Duplicate".to_string(), + email: "alice@example.com".to_string(), // Already exists + initial_metadata: None, + }; + + let result = server.create_user(duplicate_request).await; + assert!(result.is_err()); + match result.unwrap_err() { + UserError::Duplicate { field } => assert_eq!(field, "email"), + _ => panic!("Expected Duplicate error"), + } + } + + #[tokio::test] + async fn test_get_user() { + let server = TypeSystemServer::with_defaults(); + + // Test existing user + let result = server.get_user(1, Some(true)).await; + assert!(result.is_ok()); + let user = result.unwrap(); + assert_eq!(user.name, "Alice"); + assert!(!user.metadata.is_empty()); + + // Test without metadata + let result = server.get_user(1, Some(false)).await; + assert!(result.is_ok()); + let user = result.unwrap(); + assert!(user.metadata.is_empty()); + + // Test non-existent user + let result = server.get_user(999, None).await; + assert!(result.is_err()); + match result.unwrap_err() { + UserError::NotFound { id } => assert_eq!(id, 999), + _ => panic!("Expected NotFound error"), + } + } + + #[tokio::test] + async fn test_update_user() { + let server = TypeSystemServer::with_defaults(); + + let update_request = UpdateUserRequest { + name: Some("Alice Updated".to_string()), + email: None, + active: Some(false), + metadata_updates: Some( + [("status".to_string(), "updated".to_string())] + .into_iter() + .collect(), + ), + }; + + let result = server.update_user(1, update_request).await; + assert!(result.is_ok()); + + let user = result.unwrap(); + assert_eq!(user.name, "Alice Updated"); + assert!(!user.active); + assert_eq!(user.metadata.get("status"), Some(&"updated".to_string())); + assert_eq!(user.metadata.get("role"), Some(&"admin".to_string())); // Should preserve existing + } + + #[tokio::test] + async fn test_list_users_pagination() { + let server = TypeSystemServer::with_defaults(); + + let params = PaginationParams { + limit: Some(1), + offset: Some(0), + sort_by: Some("name".to_string()), + order: Some("asc".to_string()), + }; + + let result = server.list_users(params).await; + assert_eq!(result.items.len(), 1); + assert_eq!(result.total, 2); + assert_eq!(result.limit, 1); + assert_eq!(result.offset, 0); + assert_eq!(result.items[0].name, "Alice"); // Should be first alphabetically + } + + #[tokio::test] + async fn test_user_role_enum() { + let server = TypeSystemServer::with_defaults(); + + let result = server.set_user_role(1, UserRole::Moderator).await; + assert!(result.is_ok()); + assert!(result.unwrap().contains("moderator")); + + // Verify the role was set + let user = server.get_user(1, Some(true)).await.unwrap(); + assert_eq!(user.metadata.get("role"), Some(&"moderator".to_string())); + } + + #[tokio::test] + async fn test_batch_update_metadata() { + let server = TypeSystemServer::with_defaults(); + + let mut updates = HashMap::new(); + updates.insert( + 1, + [("batch_key".to_string(), "batch_value".to_string())] + .into_iter() + .collect(), + ); + updates.insert( + 2, + [("another_key".to_string(), "another_value".to_string())] + .into_iter() + .collect(), + ); + updates.insert( + 999, + [("nonexistent".to_string(), "value".to_string())] + .into_iter() + .collect(), + ); // Should be ignored + + let result = server.batch_update_metadata(updates).await; + assert!(result.is_ok()); + + let updated_ids = result.unwrap(); + assert_eq!(updated_ids.len(), 2); + assert!(updated_ids.contains(&1)); + assert!(updated_ids.contains(&2)); + assert!(!updated_ids.contains(&999)); + + // Verify updates were applied + let user1 = server.get_user(1, Some(true)).await.unwrap(); + assert_eq!( + user1.metadata.get("batch_key"), + Some(&"batch_value".to_string()) + ); + } + + #[tokio::test] + async fn test_search_users_complex() { + let server = TypeSystemServer::with_defaults(); + + // Search by query + let result = server + .search_users(Some("alice".to_string()), None, None) + .await; + assert!(result.is_ok()); + let users = result.unwrap(); + assert_eq!(users.len(), 1); + assert_eq!(users[0].name, "Alice"); + + // Search by metadata filter + let mut filters = HashMap::new(); + filters.insert("role".to_string(), "admin".to_string()); + let result = server.search_users(None, Some(filters), None).await; + assert!(result.is_ok()); + let users = result.unwrap(); + assert_eq!(users.len(), 1); + assert_eq!(users[0].name, "Alice"); + + // Search with limit + let result = server.search_users(None, None, Some(1)).await; + assert!(result.is_ok()); + let users = result.unwrap(); + assert_eq!(users.len(), 1); + } + + #[tokio::test] + async fn test_user_profile_resource() { + let server = TypeSystemServer::with_defaults(); + + let result = server.user_profile_resource("1".to_string()).await; + assert!(result.is_ok()); + + let json_value = result.unwrap(); + assert_eq!(json_value["name"], "Alice"); + assert_eq!(json_value["email"], "alice@example.com"); + assert_eq!(json_value["active"], true); + + // Test invalid ID + let result = server.user_profile_resource("invalid".to_string()).await; + assert!(result.is_err()); + + // Test non-existent user + let result = server.user_profile_resource("999".to_string()).await; + assert!(result.is_err()); + } + + #[tokio::test] + async fn test_user_prompt_complex_types() { + let server = TypeSystemServer::with_defaults(); + + let user_data = serde_json::json!({ + "id": 1, + "name": "Test User", + "email": "test@example.com", + "active": true, + "metadata": {"role": "admin"} + }); + + // Test welcome template + let result = server + .user_prompt(user_data.clone(), "welcome".to_string()) + .await; + assert!(result.is_ok()); + let message = result.unwrap(); + if let pulseengine_mcp_protocol::PromptMessageContent::Text { text } = message.content { + assert!(text.contains("Test User")); + assert!(text.contains("test@example.com")); + } + + // Test admin template + let result = server + .user_prompt(user_data.clone(), "admin".to_string()) + .await; + assert!(result.is_ok()); + + // Test non-admin user with admin template + let mut non_admin_data = user_data.clone(); + non_admin_data["metadata"]["role"] = serde_json::Value::String("user".to_string()); + let result = server + .user_prompt(non_admin_data, "admin".to_string()) + .await; + assert!(result.is_err()); + + // Test invalid user data + let invalid_data = serde_json::json!({"invalid": "data"}); + let result = server + .user_prompt(invalid_data, "welcome".to_string()) + .await; + assert!(result.is_err()); + } + + #[test] + fn test_error_types() { + let error1 = UserError::NotFound { id: 123 }; + assert_eq!(error1.to_string(), "User not found: 123"); + + let error2 = UserError::InvalidEmail { + email: "bad@".to_string(), + }; + assert_eq!(error2.to_string(), "Invalid email format: bad@"); + + let error3 = UserError::Duplicate { + field: "email".to_string(), + }; + assert_eq!(error3.to_string(), "Duplicate user: email"); + + let error4 = UserError::Validation { + message: "test error".to_string(), + }; + assert_eq!(error4.to_string(), "Validation error: test error"); + } + + #[test] + fn test_complex_type_serialization_round_trip() { + let pagination = PaginationParams { + limit: Some(50), + offset: Some(100), + sort_by: Some("name".to_string()), + order: Some("desc".to_string()), + }; + + let json = serde_json::to_string(&pagination).unwrap(); + let deserialized: PaginationParams = serde_json::from_str(&json).unwrap(); + + assert_eq!(pagination.limit, deserialized.limit); + assert_eq!(pagination.offset, deserialized.offset); + assert_eq!(pagination.sort_by, deserialized.sort_by); + assert_eq!(pagination.order, deserialized.order); + } + + #[test] + fn test_generic_types() { + let response = PaginatedResponse { + items: vec!["item1".to_string(), "item2".to_string()], + total: 100, + limit: 10, + offset: 20, + }; + + let json = serde_json::to_string(&response).unwrap(); + let deserialized: PaginatedResponse = serde_json::from_str(&json).unwrap(); + + assert_eq!(response.items, deserialized.items); + assert_eq!(response.total, deserialized.total); + } +} diff --git a/mcp-monitoring/src/collector_tests.rs b/mcp-monitoring/src/collector_tests.rs index 95a73b93..ae4e5b47 100644 --- a/mcp-monitoring/src/collector_tests.rs +++ b/mcp-monitoring/src/collector_tests.rs @@ -368,7 +368,7 @@ mod tests { let metrics = collector.get_current_metrics().await; assert!(metrics.error_rate > 0.0); // Should have error rate from concurrent errors assert_eq!(metrics.requests_total, 50); // 10 tasks * 5 requests each - // Approximately 50% error rate since j % 2 == 0 determines success/error + // Approximately 50% error rate since j % 2 == 0 determines success/error assert!(metrics.error_rate >= 0.4 && metrics.error_rate <= 0.6); } diff --git a/mcp-protocol/src/validation.rs b/mcp-protocol/src/validation.rs index 2c1f8795..d03bbf4c 100644 --- a/mcp-protocol/src/validation.rs +++ b/mcp-protocol/src/validation.rs @@ -156,7 +156,7 @@ impl Validator { .all(|c| c.is_alphanumeric() || c == '_' || c == '-' || c == '.') { return Err(Error::validation_error( - "Prompt name must contain only alphanumeric characters, underscores, hyphens, and dots" + "Prompt name must contain only alphanumeric characters, underscores, hyphens, and dots", )); } @@ -219,7 +219,7 @@ impl Validator { } "string" | "number" | "integer" | "boolean" | "null" => { return Err(Error::validation_error( - "Tool output schema should define structured data (object or array), not primitive types" + "Tool output schema should define structured data (object or array), not primitive types", )); } _ => { @@ -391,10 +391,12 @@ mod tests { let args = HashMap::new(); let result = Validator::validate_tool_arguments(&args, &schema); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Required argument 'name' is missing")); + assert!( + result + .unwrap_err() + .message + .contains("Required argument 'name' is missing") + ); // Valid schema with multiple required fields let schema = json!({ @@ -416,10 +418,12 @@ mod tests { args.insert("name".to_string(), json!("John")); let result = Validator::validate_tool_arguments(&args, &schema); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Required argument 'email' is missing")); + assert!( + result + .unwrap_err() + .message + .contains("Required argument 'email' is missing") + ); // Schema without properties let schema = json!({ @@ -523,10 +527,12 @@ mod tests { }); let result = Validator::validate_tool_output_schema(&invalid_primitive_schema); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("should define structured data")); + assert!( + result + .unwrap_err() + .message + .contains("should define structured data") + ); // Invalid - object without properties let invalid_object_schema = json!({ @@ -534,10 +540,12 @@ mod tests { }); let result = Validator::validate_tool_output_schema(&invalid_object_schema); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("must define properties")); + assert!( + result + .unwrap_err() + .message + .contains("must define properties") + ); // Invalid - object with invalid properties let invalid_props_schema = json!({ @@ -546,10 +554,12 @@ mod tests { }); let result = Validator::validate_tool_output_schema(&invalid_props_schema); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("properties must be an object")); + assert!( + result + .unwrap_err() + .message + .contains("properties must be an object") + ); // Invalid - missing type field let no_type_schema = json!({ @@ -557,10 +567,12 @@ mod tests { }); let result = Validator::validate_tool_output_schema(&no_type_schema); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("JSON schema must have a 'type' field")); + assert!( + result + .unwrap_err() + .message + .contains("JSON schema must have a 'type' field") + ); } #[test] @@ -723,32 +735,40 @@ mod tests { // Invalid empty strings let result = Validator::validate_non_empty("", "field"); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("field cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("field cannot be empty") + ); let result = Validator::validate_non_empty(" ", "field"); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("field cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("field cannot be empty") + ); let result = Validator::validate_non_empty("\t\n\r", "field"); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("field cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("field cannot be empty") + ); // Test with different field names let result = Validator::validate_non_empty("", "tool_name"); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("tool_name cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("tool_name cannot be empty") + ); } #[test] @@ -769,17 +789,21 @@ mod tests { // Invalid tool names let result = Validator::validate_tool_name(""); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Tool name cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("Tool name cannot be empty") + ); let result = Validator::validate_tool_name(" "); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Tool name cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("Tool name cannot be empty") + ); let result = Validator::validate_tool_name("tool name"); assert!(result.is_err()); @@ -829,45 +853,57 @@ mod tests { // Invalid schemas let result = Validator::validate_json_schema(&json!("not an object")); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("JSON schema must be an object")); + assert!( + result + .unwrap_err() + .message + .contains("JSON schema must be an object") + ); let result = Validator::validate_json_schema(&json!(123)); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("JSON schema must be an object")); + assert!( + result + .unwrap_err() + .message + .contains("JSON schema must be an object") + ); let result = Validator::validate_json_schema(&json!([])); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("JSON schema must be an object")); + assert!( + result + .unwrap_err() + .message + .contains("JSON schema must be an object") + ); let result = Validator::validate_json_schema(&json!(null)); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("JSON schema must be an object")); + assert!( + result + .unwrap_err() + .message + .contains("JSON schema must be an object") + ); let result = Validator::validate_json_schema(&json!({"properties": {}})); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("JSON schema must have a 'type' field")); + assert!( + result + .unwrap_err() + .message + .contains("JSON schema must have a 'type' field") + ); let result = Validator::validate_json_schema(&json!({})); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("JSON schema must have a 'type' field")); + assert!( + result + .unwrap_err() + .message + .contains("JSON schema must have a 'type' field") + ); } #[test] @@ -878,70 +914,88 @@ mod tests { assert!(Validator::validate_pagination(None, Some(1)).is_ok()); assert!(Validator::validate_pagination(Some("cursor"), Some(1)).is_ok()); assert!(Validator::validate_pagination(Some("cursor"), Some(1000)).is_ok()); - assert!(Validator::validate_pagination( - Some("very-long-cursor-value-that-should-still-be-valid"), - Some(500) - ) - .is_ok()); + assert!( + Validator::validate_pagination( + Some("very-long-cursor-value-that-should-still-be-valid"), + Some(500) + ) + .is_ok() + ); // Invalid cursor values let result = Validator::validate_pagination(Some(""), None); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Cursor cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("Cursor cannot be empty") + ); let result = Validator::validate_pagination(Some(" "), None); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Cursor cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("Cursor cannot be empty") + ); let result = Validator::validate_pagination(Some("\t\n\r"), None); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Cursor cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("Cursor cannot be empty") + ); // Invalid limit values let result = Validator::validate_pagination(None, Some(0)); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Limit must be greater than 0")); + assert!( + result + .unwrap_err() + .message + .contains("Limit must be greater than 0") + ); let result = Validator::validate_pagination(None, Some(1001)); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Limit cannot exceed 1000")); + assert!( + result + .unwrap_err() + .message + .contains("Limit cannot exceed 1000") + ); let result = Validator::validate_pagination(None, Some(u32::MAX)); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Limit cannot exceed 1000")); + assert!( + result + .unwrap_err() + .message + .contains("Limit cannot exceed 1000") + ); // Test with both invalid cursor and limit let result = Validator::validate_pagination(Some(""), Some(0)); assert!(result.is_err()); // Should fail on cursor first - assert!(result - .unwrap_err() - .message - .contains("Cursor cannot be empty")); + assert!( + result + .unwrap_err() + .message + .contains("Cursor cannot be empty") + ); let result = Validator::validate_pagination(Some("valid-cursor"), Some(0)); assert!(result.is_err()); - assert!(result - .unwrap_err() - .message - .contains("Limit must be greater than 0")); + assert!( + result + .unwrap_err() + .message + .contains("Limit must be greater than 0") + ); } } diff --git a/mcp-security/src/config_tests.rs b/mcp-security/src/config_tests.rs index 01b78149..baa7f6bc 100644 --- a/mcp-security/src/config_tests.rs +++ b/mcp-security/src/config_tests.rs @@ -175,9 +175,11 @@ mod tests { assert_eq!(config.cors_origins.len(), 5); assert!(config.cors_origins.contains(&"*".to_string())); - assert!(config - .cors_origins - .contains(&"https://*.example.com".to_string())); + assert!( + config + .cors_origins + .contains(&"https://*.example.com".to_string()) + ); } #[test] diff --git a/mcp-security/src/validation_tests.rs b/mcp-security/src/validation_tests.rs index 89d4f615..debc293b 100644 --- a/mcp-security/src/validation_tests.rs +++ b/mcp-security/src/validation_tests.rs @@ -3,7 +3,7 @@ #[cfg(test)] mod tests { use super::super::*; - use pulseengine_mcp_protocol::{error::ErrorCode, Request}; + use pulseengine_mcp_protocol::{Request, error::ErrorCode}; use serde_json::json; fn create_request(jsonrpc: &str, method: &str) -> Request { diff --git a/mcp-server/src/alerting_endpoint.rs b/mcp-server/src/alerting_endpoint.rs index c91fa568..10ad9a15 100644 --- a/mcp-server/src/alerting_endpoint.rs +++ b/mcp-server/src/alerting_endpoint.rs @@ -1,11 +1,11 @@ //! Alerting management endpoints use axum::{ + Router, extract::{Path, State}, http::StatusCode, response::{IntoResponse, Json}, routing::{get, post}, - Router, }; use pulseengine_mcp_logging::{AlertManager, AlertSeverity, AlertState}; use serde::{Deserialize, Serialize}; diff --git a/mcp-server/src/backend_tests.rs b/mcp-server/src/backend_tests.rs index 61ab0e1b..d77a60df 100644 --- a/mcp-server/src/backend_tests.rs +++ b/mcp-server/src/backend_tests.rs @@ -10,24 +10,32 @@ use std::fmt; #[test] fn test_backend_error_creation() { let config_err = BackendError::configuration("Config test"); - assert!(config_err - .to_string() - .contains("Configuration error: Config test")); + assert!( + config_err + .to_string() + .contains("Configuration error: Config test") + ); let connection_err = BackendError::connection("Connection test"); - assert!(connection_err - .to_string() - .contains("Connection error: Connection test")); + assert!( + connection_err + .to_string() + .contains("Connection error: Connection test") + ); let not_supported_err = BackendError::not_supported("Not supported test"); - assert!(not_supported_err - .to_string() - .contains("Operation not supported: Not supported test")); + assert!( + not_supported_err + .to_string() + .contains("Operation not supported: Not supported test") + ); let internal_err = BackendError::internal("Internal test"); - assert!(internal_err - .to_string() - .contains("Internal backend error: Internal test")); + assert!( + internal_err + .to_string() + .contains("Internal backend error: Internal test") + ); } #[test] diff --git a/mcp-server/src/dashboard_endpoint.rs b/mcp-server/src/dashboard_endpoint.rs index f5c1db79..242e0adf 100644 --- a/mcp-server/src/dashboard_endpoint.rs +++ b/mcp-server/src/dashboard_endpoint.rs @@ -1,11 +1,11 @@ //! Dashboard endpoints for metrics visualization use axum::{ + Router, extract::{Path, State}, http::StatusCode, response::{Html, IntoResponse, Json}, routing::get, - Router, }; use pulseengine_mcp_logging::DashboardManager; use serde::{Deserialize, Serialize}; diff --git a/mcp-server/src/handler.rs b/mcp-server/src/handler.rs index fff2a2c0..b468b90a 100644 --- a/mcp-server/src/handler.rs +++ b/mcp-server/src/handler.rs @@ -467,18 +467,18 @@ mod tests { use crate::backend::McpBackend; use crate::middleware::MiddlewareStack; use async_trait::async_trait; - use pulseengine_mcp_auth::config::AuthConfig; use pulseengine_mcp_auth::AuthenticationManager; + use pulseengine_mcp_auth::config::AuthConfig; use pulseengine_mcp_logging::ErrorClassification; use pulseengine_mcp_protocol::{ - error::ErrorCode, CallToolRequestParam, CallToolResult, CompleteRequestParam, - CompleteResult, CompletionInfo, Content, Error, GetPromptRequestParam, GetPromptResult, - Implementation, InitializeResult, ListPromptsResult, ListResourceTemplatesResult, - ListResourcesResult, ListToolsResult, LoggingCapability, PaginatedRequestParam, Prompt, - PromptMessage, PromptMessageContent, PromptMessageRole, PromptsCapability, ProtocolVersion, - ReadResourceRequestParam, ReadResourceResult, Request, Resource, ResourceContents, - ResourcesCapability, ServerCapabilities, ServerInfo, SetLevelRequestParam, - SubscribeRequestParam, Tool, ToolsCapability, UnsubscribeRequestParam, + CallToolRequestParam, CallToolResult, CompleteRequestParam, CompleteResult, CompletionInfo, + Content, Error, GetPromptRequestParam, GetPromptResult, Implementation, InitializeResult, + ListPromptsResult, ListResourceTemplatesResult, ListResourcesResult, ListToolsResult, + LoggingCapability, PaginatedRequestParam, Prompt, PromptMessage, PromptMessageContent, + PromptMessageRole, PromptsCapability, ProtocolVersion, ReadResourceRequestParam, + ReadResourceResult, Request, Resource, ResourceContents, ResourcesCapability, + ServerCapabilities, ServerInfo, SetLevelRequestParam, SubscribeRequestParam, Tool, + ToolsCapability, UnsubscribeRequestParam, error::ErrorCode, }; use serde_json::json; use std::sync::Arc; diff --git a/mcp-server/src/handler_tests.rs b/mcp-server/src/handler_tests.rs index 65db570c..a0e23eca 100644 --- a/mcp-server/src/handler_tests.rs +++ b/mcp-server/src/handler_tests.rs @@ -4,7 +4,7 @@ use crate::backend::{BackendError, McpBackend}; use crate::handler::{GenericServerHandler, HandlerError}; use crate::middleware::MiddlewareStack; use async_trait::async_trait; -use pulseengine_mcp_auth::{config::StorageConfig, AuthConfig, AuthenticationManager}; +use pulseengine_mcp_auth::{AuthConfig, AuthenticationManager, config::StorageConfig}; use pulseengine_mcp_protocol::error::ErrorCode; use pulseengine_mcp_protocol::*; use std::error::Error as StdError; @@ -268,19 +268,25 @@ async fn create_test_handler() -> GenericServerHandler { #[test] fn test_handler_error_types() { let auth_err = HandlerError::Authentication("Auth failed".to_string()); - assert!(auth_err - .to_string() - .contains("Authentication failed: Auth failed")); + assert!( + auth_err + .to_string() + .contains("Authentication failed: Auth failed") + ); let authz_err = HandlerError::Authorization("Authz failed".to_string()); - assert!(authz_err - .to_string() - .contains("Authorization failed: Authz failed")); + assert!( + authz_err + .to_string() + .contains("Authorization failed: Authz failed") + ); let backend_err = HandlerError::Backend("Backend failed".to_string()); - assert!(backend_err - .to_string() - .contains("Backend error: Backend failed")); + assert!( + backend_err + .to_string() + .contains("Backend error: Backend failed") + ); let protocol_err = HandlerError::Protocol(Error::internal_error("Protocol failed")); assert!(protocol_err.to_string().contains("Protocol error:")); diff --git a/mcp-server/src/health_endpoint.rs b/mcp-server/src/health_endpoint.rs index 68baf34b..23ec7f42 100644 --- a/mcp-server/src/health_endpoint.rs +++ b/mcp-server/src/health_endpoint.rs @@ -1,13 +1,13 @@ //! Health check endpoints for Kubernetes and monitoring -use crate::backend::McpBackend; use crate::McpServer; +use crate::backend::McpBackend; use axum::{ + Router, extract::State, http::StatusCode, response::{IntoResponse, Json}, routing::get, - Router, }; use serde::{Deserialize, Serialize}; use std::sync::Arc; diff --git a/mcp-server/src/metrics_endpoint.rs b/mcp-server/src/metrics_endpoint.rs index 16b69def..5dc75ee4 100644 --- a/mcp-server/src/metrics_endpoint.rs +++ b/mcp-server/src/metrics_endpoint.rs @@ -1,6 +1,6 @@ //! Metrics endpoints for monitoring and observability -use axum::{extract::State, http::StatusCode, response::IntoResponse, routing::get, Router}; +use axum::{Router, extract::State, http::StatusCode, response::IntoResponse, routing::get}; use prometheus::{Counter, Encoder, Gauge, Histogram, Registry, TextEncoder}; use pulseengine_mcp_logging::get_metrics as get_logging_metrics; use pulseengine_mcp_monitoring::MetricsCollector; diff --git a/mcp-server/src/middleware_tests.rs b/mcp-server/src/middleware_tests.rs index 7d9c858b..f1f4e963 100644 --- a/mcp-server/src/middleware_tests.rs +++ b/mcp-server/src/middleware_tests.rs @@ -3,7 +3,7 @@ use crate::context::RequestContext; use crate::middleware::{Middleware, MiddlewareStack}; use async_trait::async_trait; -use pulseengine_mcp_auth::{config::StorageConfig, AuthConfig, AuthenticationManager}; +use pulseengine_mcp_auth::{AuthConfig, AuthenticationManager, config::StorageConfig}; use pulseengine_mcp_monitoring::{MetricsCollector, MonitoringConfig}; use pulseengine_mcp_protocol::*; use pulseengine_mcp_security::{SecurityConfig, SecurityMiddleware}; diff --git a/mcp-server/src/server_tests.rs b/mcp-server/src/server_tests.rs index 60cb954e..d369631b 100644 --- a/mcp-server/src/server_tests.rs +++ b/mcp-server/src/server_tests.rs @@ -3,7 +3,7 @@ use crate::backend::{BackendError, McpBackend}; use crate::server::{HealthStatus, McpServer, ServerConfig, ServerError}; use async_trait::async_trait; -use pulseengine_mcp_auth::{config::StorageConfig, AuthConfig}; +use pulseengine_mcp_auth::{AuthConfig, config::StorageConfig}; use pulseengine_mcp_monitoring::MonitoringConfig; use pulseengine_mcp_protocol::*; use pulseengine_mcp_security::SecurityConfig; @@ -156,34 +156,48 @@ impl McpBackend for MockServerBackend { #[test] fn test_server_error_types() { let config_err = ServerError::Configuration("Config failed".to_string()); - assert!(config_err - .to_string() - .contains("Server configuration error: Config failed")); + assert!( + config_err + .to_string() + .contains("Server configuration error: Config failed") + ); let transport_err = ServerError::Transport("Transport failed".to_string()); - assert!(transport_err - .to_string() - .contains("Transport error: Transport failed")); + assert!( + transport_err + .to_string() + .contains("Transport error: Transport failed") + ); let auth_err = ServerError::Authentication("Auth failed".to_string()); - assert!(auth_err - .to_string() - .contains("Authentication error: Auth failed")); + assert!( + auth_err + .to_string() + .contains("Authentication error: Auth failed") + ); let backend_err = ServerError::Backend("Backend failed".to_string()); - assert!(backend_err - .to_string() - .contains("Backend error: Backend failed")); - - assert!(ServerError::AlreadyRunning - .to_string() - .contains("Server already running")); - assert!(ServerError::NotRunning - .to_string() - .contains("Server not running")); - assert!(ServerError::ShutdownTimeout - .to_string() - .contains("Shutdown timeout")); + assert!( + backend_err + .to_string() + .contains("Backend error: Backend failed") + ); + + assert!( + ServerError::AlreadyRunning + .to_string() + .contains("Server already running") + ); + assert!( + ServerError::NotRunning + .to_string() + .contains("Server not running") + ); + assert!( + ServerError::ShutdownTimeout + .to_string() + .contains("Shutdown timeout") + ); } #[test] diff --git a/mcp-transport/examples/complete_mcp_server.rs b/mcp-transport/examples/complete_mcp_server.rs index 03a2bc16..21d753f7 100644 --- a/mcp-transport/examples/complete_mcp_server.rs +++ b/mcp-transport/examples/complete_mcp_server.rs @@ -11,7 +11,7 @@ //! - Error handling for unknown methods use pulseengine_mcp_protocol::{Error, Request, Response}; -use pulseengine_mcp_transport::{http::HttpTransport, RequestHandler, Transport}; +use pulseengine_mcp_transport::{RequestHandler, Transport, http::HttpTransport}; use serde_json::json; use tracing::{debug, info, warn}; diff --git a/mcp-transport/examples/debug_full_request.rs b/mcp-transport/examples/debug_full_request.rs index 70ce0df3..75f27005 100644 --- a/mcp-transport/examples/debug_full_request.rs +++ b/mcp-transport/examples/debug_full_request.rs @@ -1,11 +1,11 @@ //! Debug server to capture full request details use axum::{ + Router, extract::{Query, Request}, http::Uri, response::Json, routing::get, - Router, }; use serde::{Deserialize, Serialize}; use std::collections::HashMap; diff --git a/mcp-transport/examples/debug_query_params.rs b/mcp-transport/examples/debug_query_params.rs index f0b2307a..59f46ada 100644 --- a/mcp-transport/examples/debug_query_params.rs +++ b/mcp-transport/examples/debug_query_params.rs @@ -1,6 +1,6 @@ //! Debug server to check query parameter parsing -use axum::{extract::Query, response::Json, routing::get, Router}; +use axum::{Router, extract::Query, response::Json, routing::get}; use serde::{Deserialize, Serialize}; use std::collections::HashMap; use tracing::info; diff --git a/mcp-transport/examples/minimal_inspector_test.rs b/mcp-transport/examples/minimal_inspector_test.rs index d41fafdd..bcf24dfc 100644 --- a/mcp-transport/examples/minimal_inspector_test.rs +++ b/mcp-transport/examples/minimal_inspector_test.rs @@ -1,11 +1,11 @@ //! Minimal test to determine what MCP Inspector expects use axum::{ + Router, extract::Query, http::{HeaderMap, StatusCode, Uri}, response::{IntoResponse, Json, Response}, routing::{get, post}, - Router, }; use serde::Deserialize; use serde_json::json; diff --git a/mcp-transport/examples/test_http_sse.rs b/mcp-transport/examples/test_http_sse.rs index d645996d..3b9a117d 100644 --- a/mcp-transport/examples/test_http_sse.rs +++ b/mcp-transport/examples/test_http_sse.rs @@ -1,10 +1,10 @@ //! Test HTTP/SSE transport implementation use pulseengine_mcp_protocol::{Request, Response}; -use pulseengine_mcp_transport::{http::HttpTransport, RequestHandler, Transport}; +use pulseengine_mcp_transport::{RequestHandler, Transport, http::HttpTransport}; use serde_json::json; use std::sync::Arc; -use tokio::time::{sleep, Duration}; +use tokio::time::{Duration, sleep}; use tracing::{error, info}; // Simple echo handler diff --git a/mcp-transport/examples/test_mcp_inspector.rs b/mcp-transport/examples/test_mcp_inspector.rs index 12424520..7cc1f6a9 100644 --- a/mcp-transport/examples/test_mcp_inspector.rs +++ b/mcp-transport/examples/test_mcp_inspector.rs @@ -1,7 +1,7 @@ //! Test server that mimics what MCP Inspector expects use pulseengine_mcp_protocol::{Request, Response}; -use pulseengine_mcp_transport::{http::HttpTransport, RequestHandler, Transport}; +use pulseengine_mcp_transport::{RequestHandler, Transport, http::HttpTransport}; use serde_json::json; use tracing::{debug, info}; diff --git a/mcp-transport/examples/test_mcp_unified.rs b/mcp-transport/examples/test_mcp_unified.rs index 28929cef..df2b1b28 100644 --- a/mcp-transport/examples/test_mcp_unified.rs +++ b/mcp-transport/examples/test_mcp_unified.rs @@ -1,7 +1,7 @@ //! Unified MCP server that handles both SSE and streamable-http clients use pulseengine_mcp_protocol::{Request, Response}; -use pulseengine_mcp_transport::{http::HttpTransport, RequestHandler, Transport}; +use pulseengine_mcp_transport::{RequestHandler, Transport, http::HttpTransport}; use serde_json::json; use tracing::{debug, info}; diff --git a/mcp-transport/examples/test_streamable_http.rs b/mcp-transport/examples/test_streamable_http.rs index 9bdad487..820de4fa 100644 --- a/mcp-transport/examples/test_streamable_http.rs +++ b/mcp-transport/examples/test_streamable_http.rs @@ -2,7 +2,7 @@ use pulseengine_mcp_protocol::{Request, Response}; use pulseengine_mcp_transport::{ - streamable_http::StreamableHttpTransport, RequestHandler, Transport, + RequestHandler, Transport, streamable_http::StreamableHttpTransport, }; use serde_json::json; use tracing::info; diff --git a/mcp-transport/src/batch.rs b/mcp-transport/src/batch.rs index 8983e0d4..2a14066c 100644 --- a/mcp-transport/src/batch.rs +++ b/mcp-transport/src/batch.rs @@ -1,6 +1,6 @@ //! JSON-RPC batch message handling -use crate::{validation::validate_batch, RequestHandler, TransportError}; +use crate::{RequestHandler, TransportError, validation::validate_batch}; use pulseengine_mcp_protocol::{Request, Response}; use serde_json::Value; use tracing::debug; diff --git a/mcp-transport/src/batch_tests.rs b/mcp-transport/src/batch_tests.rs index 57666652..391fb634 100644 --- a/mcp-transport/src/batch_tests.rs +++ b/mcp-transport/src/batch_tests.rs @@ -5,7 +5,7 @@ mod tests { use super::super::batch::*; use crate::TransportError; use pulseengine_mcp_protocol::{Error as McpError, Request, Response}; - use serde_json::{json, Value}; + use serde_json::{Value, json}; // Mock handler for testing fn mock_handler( diff --git a/mcp-transport/src/http.rs b/mcp-transport/src/http.rs index 74dd7b67..89294978 100644 --- a/mcp-transport/src/http.rs +++ b/mcp-transport/src/http.rs @@ -1,28 +1,28 @@ //! HTTP transport with Server-Sent Events (SSE) support use crate::{ - batch::{process_batch, JsonRpcMessage}, - validation::validate_message_string, RequestHandler, Transport, TransportError, + batch::{JsonRpcMessage, process_batch}, + validation::validate_message_string, }; use async_trait::async_trait; use axum::response::sse::{Event, KeepAlive}; use axum::{ + Router, extract::{Query, State}, http::{ - header::{AUTHORIZATION, ORIGIN}, HeaderMap, StatusCode, + header::{AUTHORIZATION, ORIGIN}, }, response::{IntoResponse, Response as AxumResponse, Sse}, routing::{get, post}, - Router, }; // futures_util used for async_stream // mcp_protocol types are imported via batch module use serde::Deserialize; use serde_json; use std::{collections::HashMap, net::SocketAddr, sync::Arc, time::Duration}; -use tokio::sync::{broadcast, Mutex, RwLock}; +use tokio::sync::{Mutex, RwLock, broadcast}; use tower::ServiceBuilder; use tower_http::cors::CorsLayer; use tracing::{debug, error, info, warn}; @@ -419,7 +419,10 @@ async fn handle_post( if wants_json_response { // New Streamable HTTP transport - return response directly - info!("Using Streamable HTTP transport, returning response directly for session: {}, Accept: {}", session_id, accept_header); + info!( + "Using Streamable HTTP transport, returning response directly for session: {}, Accept: {}", + session_id, accept_header + ); debug!("Direct response: {}", response_json); Ok(AxumResponse::builder() .status(StatusCode::OK) @@ -461,7 +464,10 @@ async fn handle_post( for (sid, session) in sessions.iter() { match session.event_sender.send(response_json.clone()) { Ok(num_receivers) => { - info!("Response sent successfully to {} receivers on fallback session: {}", num_receivers, sid); + info!( + "Response sent successfully to {} receivers on fallback session: {}", + num_receivers, sid + ); sent = true; break; } @@ -1015,10 +1021,12 @@ mod tests { let headers = HeaderMap::new(); let result = HttpTransport::validate_origin(&config, &headers); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Missing Origin header")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Missing Origin header") + ); } #[test] @@ -1033,10 +1041,12 @@ mod tests { headers.insert(ORIGIN, HeaderValue::from_bytes(&[0xFF, 0xFE]).unwrap()); let result = HttpTransport::validate_origin(&config, &headers); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Invalid Origin header")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Invalid Origin header") + ); } // === Authentication Tests === @@ -1063,10 +1073,12 @@ mod tests { let headers = HeaderMap::new(); let result = HttpTransport::validate_auth(&config, &headers); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Missing Authorization header")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Missing Authorization header") + ); } #[test] @@ -1084,10 +1096,12 @@ mod tests { ); let result = HttpTransport::validate_auth(&config, &headers); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Invalid Authorization header")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Invalid Authorization header") + ); } #[test] @@ -1118,10 +1132,12 @@ mod tests { headers.insert(AUTHORIZATION, "Bearer invalid-token".parse().unwrap()); let result = HttpTransport::validate_auth(&config, &headers); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Invalid bearer token")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Invalid bearer token") + ); } #[test] @@ -1136,18 +1152,22 @@ mod tests { headers.insert(AUTHORIZATION, "Basic dXNlcjpwYXNz".parse().unwrap()); let result = HttpTransport::validate_auth(&config, &headers); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Invalid Authorization format")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Invalid Authorization format") + ); headers.insert(AUTHORIZATION, "just-a-token".parse().unwrap()); let result = HttpTransport::validate_auth(&config, &headers); assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Invalid Authorization format")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Invalid Authorization format") + ); } // === Session Management Tests === @@ -1296,10 +1316,12 @@ mod tests { let transport = HttpTransport::new(3000); let result = transport.broadcast_message("test message").await; assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("Transport not started")); + assert!( + result + .unwrap_err() + .to_string() + .contains("Transport not started") + ); } #[tokio::test] @@ -1524,13 +1546,15 @@ mod tests { let response = result.unwrap(); assert_eq!(response.status(), StatusCode::OK); - assert!(response - .headers() - .get("Content-Type") - .unwrap() - .to_str() - .unwrap() - .contains("application/json")); + assert!( + response + .headers() + .get("Content-Type") + .unwrap() + .to_str() + .unwrap() + .contains("application/json") + ); assert!(response.headers().contains_key("Mcp-Session-Id")); } @@ -1777,10 +1801,12 @@ mod tests { let transport = HttpTransport::new(3000); let result = transport.health_check().await; assert!(result.is_err()); - assert!(result - .unwrap_err() - .to_string() - .contains("HTTP transport not running")); + assert!( + result + .unwrap_err() + .to_string() + .contains("HTTP transport not running") + ); } // === Integration Tests === @@ -1916,12 +1942,14 @@ mod tests { assert_eq!(transport.config.port, 65535); assert_eq!(transport.config.max_message_size, 0); assert_eq!(transport.config.session_timeout_secs, 0); - assert!(transport - .config - .allowed_origins - .as_ref() - .unwrap() - .is_empty()); + assert!( + transport + .config + .allowed_origins + .as_ref() + .unwrap() + .is_empty() + ); } #[test] diff --git a/mcp-transport/src/http_test.rs b/mcp-transport/src/http_test.rs index 163cb5c5..40cd956f 100644 --- a/mcp-transport/src/http_test.rs +++ b/mcp-transport/src/http_test.rs @@ -2,10 +2,10 @@ #[cfg(test)] mod tests { - use crate::{http::HttpTransport, RequestHandler, Transport}; + use crate::{RequestHandler, Transport, http::HttpTransport}; use pulseengine_mcp_protocol::{Request, Response}; use serde_json::json; - use tokio::time::{sleep, Duration}; + use tokio::time::{Duration, sleep}; // Test handler that echoes requests fn test_handler( diff --git a/mcp-transport/src/http_tests.rs b/mcp-transport/src/http_tests.rs index 8676baee..57d424b7 100644 --- a/mcp-transport/src/http_tests.rs +++ b/mcp-transport/src/http_tests.rs @@ -4,10 +4,10 @@ mod tests { use super::super::http::*; use crate::{Transport, TransportError}; - use axum::http::header::{AUTHORIZATION, ORIGIN}; use axum::http::HeaderMap; + use axum::http::header::{AUTHORIZATION, ORIGIN}; use pulseengine_mcp_protocol::{Request, Response}; - use serde_json::{json, Value}; + use serde_json::{Value, json}; // Mock handler for testing fn mock_handler( diff --git a/mcp-transport/src/stdio.rs b/mcp-transport/src/stdio.rs index 43398d2b..3db56724 100644 --- a/mcp-transport/src/stdio.rs +++ b/mcp-transport/src/stdio.rs @@ -1,9 +1,9 @@ //! MCP-compliant Standard I/O transport implementation use crate::{ - batch::{create_error_response, process_batch, JsonRpcMessage}, - validation::{extract_id_from_malformed, validate_message_string}, RequestHandler, Transport, TransportError, + batch::{JsonRpcMessage, create_error_response, process_batch}, + validation::{extract_id_from_malformed, validate_message_string}, }; use async_trait::async_trait; use pulseengine_mcp_protocol::Response; diff --git a/mcp-transport/src/stdio_tests.rs b/mcp-transport/src/stdio_tests.rs index 8c9f9877..ebfa45bf 100644 --- a/mcp-transport/src/stdio_tests.rs +++ b/mcp-transport/src/stdio_tests.rs @@ -5,7 +5,7 @@ mod tests { use super::super::stdio::*; use crate::{Transport, TransportError}; use pulseengine_mcp_protocol::{Error as McpError, Request, Response}; - use serde_json::{json, Value}; + use serde_json::{Value, json}; use std::sync::Arc; use tokio::io::{AsyncWriteExt, BufWriter}; diff --git a/mcp-transport/src/streamable_http.rs b/mcp-transport/src/streamable_http.rs index b36fefdf..7bfc6132 100644 --- a/mcp-transport/src/streamable_http.rs +++ b/mcp-transport/src/streamable_http.rs @@ -6,11 +6,11 @@ use crate::{RequestHandler, Transport, TransportError}; use async_trait::async_trait; use axum::{ + Json, Router, extract::{Query, State}, http::{HeaderMap, StatusCode}, response::IntoResponse, routing::{get, post}, - Json, Router, }; use serde::Deserialize; use serde_json::Value; diff --git a/mcp-transport/src/streamable_http_tests.rs b/mcp-transport/src/streamable_http_tests.rs index 54174ac4..601f5ea0 100644 --- a/mcp-transport/src/streamable_http_tests.rs +++ b/mcp-transport/src/streamable_http_tests.rs @@ -5,7 +5,7 @@ mod tests { use super::super::streamable_http::*; use crate::{Transport, TransportError}; use pulseengine_mcp_protocol::{Request, Response}; - use serde_json::{json, Value}; + use serde_json::{Value, json}; // Mock handler for testing fn mock_handler( @@ -97,10 +97,12 @@ mod tests { assert_eq!(transport.config().host, "127.0.0.1"); assert!(transport.config().enable_cors); // Initially not running, so health check should fail - assert!(tokio::runtime::Runtime::new() - .unwrap() - .block_on(transport.health_check()) - .is_err()); + assert!( + tokio::runtime::Runtime::new() + .unwrap() + .block_on(transport.health_check()) + .is_err() + ); } #[test] diff --git a/mcp-transport/src/validation_tests.rs b/mcp-transport/src/validation_tests.rs index 4866cafd..89aa3544 100644 --- a/mcp-transport/src/validation_tests.rs +++ b/mcp-transport/src/validation_tests.rs @@ -429,12 +429,16 @@ mod tests { // Test that error messages are informative let oversized = "a".repeat(MAX_MESSAGE_SIZE + 1); let size_error = validate_message_string(&oversized, Some(MAX_MESSAGE_SIZE)).unwrap_err(); - assert!(size_error - .to_string() - .contains("Message exceeds maximum size")); - assert!(size_error - .to_string() - .contains(&MAX_MESSAGE_SIZE.to_string())); + assert!( + size_error + .to_string() + .contains("Message exceeds maximum size") + ); + assert!( + size_error + .to_string() + .contains(&MAX_MESSAGE_SIZE.to_string()) + ); let invalid_json = "{invalid}"; let json_error = validate_json_rpc_message(invalid_json).unwrap_err(); diff --git a/mcp-transport/src/websocket_tests.rs b/mcp-transport/src/websocket_tests.rs index da0eb072..b0bb5412 100644 --- a/mcp-transport/src/websocket_tests.rs +++ b/mcp-transport/src/websocket_tests.rs @@ -5,7 +5,7 @@ mod tests { use super::super::websocket::*; use crate::{Transport, TransportError}; use pulseengine_mcp_protocol::{Request, Response}; - use serde_json::{json, Value}; + use serde_json::{Value, json}; // Mock handler for testing fn mock_handler( diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 92f2df47..0d0fc267 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,7 +1,7 @@ [toolchain] # Pin Rust version to ensure consistency across all environments # This file is used by rustup to automatically install and use the correct toolchain -channel = "1.85" +channel = "1.88" components = ["rustfmt", "clippy", "llvm-tools-preview"] targets = ["x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc"]