Crate pulseengine_mcp_server

Expand description

Generic MCP server infrastructure with pluggable backends

This crate provides a complete MCP server implementation that can be extended with custom backends for different domains (home automation, databases, APIs, etc.).

§Quick Start

use pulseengine_mcp_server::{McpServer, McpBackend, ServerConfig};
use pulseengine_mcp_protocol::*;
use async_trait::async_trait;

#[derive(Clone)]
struct MyBackend;

#[async_trait]
impl McpBackend for MyBackend {
    type Error = Box<dyn std::error::Error + Send + Sync>;
    type Config = ();

    async fn initialize(_: ()) -> std::result::Result<Self, Self::Error> {
        Ok(MyBackend)
    }

    fn get_server_info(&self) -> ServerInfo {
        ServerInfo {
            protocol_version: ProtocolVersion::default(),
            capabilities: ServerCapabilities::default(),
            server_info: Implementation {
                name: "My Server".to_string(),
                version: "1.0.0".to_string(),
            },
            instructions: Some("Example server".to_string()),
        }
    }

    async fn list_tools(&self, _: PaginatedRequestParam) -> std::result::Result<ListToolsResult, Self::Error> {
        Ok(ListToolsResult { tools: vec![], next_cursor: None })
    }

    async fn call_tool(&self, _: CallToolRequestParam) -> Result<CallToolResult, Self::Error> {
        Ok(CallToolResult { content: vec![], is_error: Some(false) })
    }

    // Implement other required methods (simplified for example)
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = MyBackend::initialize(()).await?;
    let config = ServerConfig::default();
    let mut server = McpServer::new(backend, config).await?;
    server.run().await?;
    Ok(())
}

§Authentication Options

The server supports multiple authentication backends for different deployment scenarios:

§File-based Authentication (Default)

use pulseengine_mcp_server::{McpServer, ServerConfig, AuthConfig};
use pulseengine_mcp_auth::config::StorageConfig;
use std::path::PathBuf;

let auth_config = AuthConfig {
    storage: StorageConfig::File {
        path: PathBuf::from("~/.pulseengine/mcp-auth/keys.enc"),
        file_permissions: 0o600,
        dir_permissions: 0o700,
        require_secure_filesystem: true,
        enable_filesystem_monitoring: false,
    },
    enabled: true,
    // ... other config
};

let server_config = ServerConfig {
    auth_config: Some(auth_config),
    // ... other config
};

§Environment Variable Authentication

For containerized deployments without filesystem access:

use pulseengine_mcp_server::{McpServer, ServerConfig, AuthConfig};
use pulseengine_mcp_auth::config::StorageConfig;

let auth_config = AuthConfig {
    storage: StorageConfig::Environment {
        prefix: "MCP_AUTH".to_string(),
    },
    enabled: true,
    // ... other config
};

// Set environment variables:
// MCP_AUTH_API_KEY_ADMIN_1=admin-key-12345
// MCP_AUTH_API_KEY_OPERATOR_1=operator-key-67890

§Memory-Only Authentication

For temporary deployments where keys don’t need persistence:

use pulseengine_mcp_server::{McpServer, ServerConfig, AuthConfig};
use pulseengine_mcp_auth::{config::StorageConfig, types::{ApiKey, Role}};
use std::collections::HashMap;

// Create memory-only auth config
let auth_config = AuthConfig::memory();

let server_config = ServerConfig {
    auth_config: Some(auth_config),
    // ... other config
};

// Add API keys programmatically during runtime
let api_key = ApiKey {
    id: "temp_key_1".to_string(),
    key: "temporary-secret-key".to_string(),
    role: Role::Admin,
    created_at: chrono::Utc::now(),
    last_used: None,
    permissions: vec![],
    rate_limit: None,
    ip_whitelist: None,
    expires_at: None,
    metadata: HashMap::new(),
};

// Add to server's auth manager after initialization
server.auth_manager().save_api_key(&api_key).await?;

§Disabled Authentication

For development or trusted environments:

let auth_config = AuthConfig::disabled();
let server_config = ServerConfig {
    auth_config: Some(auth_config),
    // ... other config
};

Re-exports§

pub use backend::BackendError;
pub use backend::McpBackend;
pub use context::RequestContext;
pub use handler::GenericServerHandler;
pub use handler::HandlerError;
pub use middleware::Middleware;
pub use middleware::MiddlewareStack;
pub use server::McpServer;
pub use server::ServerConfig;
pub use server::ServerError;
pub use pulseengine_mcp_auth as auth;
pub use pulseengine_mcp_monitoring as monitoring;
pub use pulseengine_mcp_protocol as protocol;
pub use pulseengine_mcp_security as security;
pub use pulseengine_mcp_transport as transport;

Modules§

alerting_endpoint: Alerting management endpoints
backend: Backend trait for pluggable MCP implementations
context: Request context for MCP operations
dashboard_endpoint: Dashboard endpoints for metrics visualization
error: Error types for the MCP protocol
errors: Error harmonization and convenience utilities
handler: Generic request handler for MCP protocol
health_endpoint: Health check endpoints for Kubernetes and monitoring
metrics_endpoint: Metrics endpoints for monitoring and observability
middleware: Middleware stack for request/response processing
model: MCP model types for protocol messages and data structures
server: Generic MCP server implementation
validation: Validation utilities for MCP protocol types

Macros§

mcp_error: Macro for quick error creation

Structs§

Annotations: Resource annotations
AuthConfig: Authentication configuration
AuthenticationManager: Authentication manager with comprehensive key management
CallToolRequestParam: Tool call parameters
CallToolResult: Tool call result
CompleteRequestParam: Completion request parameters
CompleteResult: Complete result
CompletionInfo: Completion information
ElicitationCapability
ElicitationRequestParam: Elicitation request parameters
ElicitationResponse: Elicitation response
ElicitationResult: Elicitation result
Error: Core MCP error type
GetPromptRequestParam: Get prompt parameters
GetPromptResult: Get prompt result
Implementation: Server implementation information
InitializeRequestParam: Initialize request parameters
InitializeResult: Initialize result
ListPromptsResult: List prompts result
ListResourceTemplatesResult: List resource templates result
ListResourcesResult: List resources result
ListToolsResult: List tools result
LoggingCapability
MetricsCollector: Metrics collector for MCP server
MonitoringConfig: Monitoring configuration
PaginatedRequestParam: Pagination parameters
Prompt: Prompt definition
PromptArgument: Prompt argument definition
PromptMessage: Prompt message
PromptsCapability
ProtocolVersion: Protocol version information
RawResource: Raw resource (for internal use)
ReadResourceRequestParam: Read resource parameters
ReadResourceResult: Read resource result
Request: JSON-RPC 2.0 Request
Resource: Resource definition
ResourceContents: Resource contents wrapper
ResourceTemplate: Resource template definition
ResourcesCapability
Response: JSON-RPC 2.0 Response
SamplingCapability
SecurityConfig: Security configuration
SecurityMiddleware: Security middleware for request/response processing
ServerCapabilities: Server capabilities configuration
ServerCapabilitiesBuilder
ServerInfo: Server information response
SetLevelRequestParam: Set logging level parameters
SubscribeRequestParam: Subscribe request parameters
TextContent: Text content struct for compatibility
Tool: Tool definition
ToolsCapability
UnsubscribeRequestParam: Unsubscribe request parameters
Validator: Protocol validation utilities

Enums§

CommonError: Common error types that backend implementers often need
Content: Content types for tool responses
ElicitationAction: Elicitation response actions
ErrorCode: MCP error codes following JSON-RPC 2.0 specification
PromptMessageContent: Prompt message content
PromptMessageRole: Prompt message role
TransportConfig: Transport configuration

Constants§

MCP_VERSION: Protocol version constants
SUPPORTED_PROTOCOL_VERSIONS

Traits§

Transport: Transport layer trait

Functions§

is_protocol_version_supported: Check if a protocol version is supported
validate_protocol_version: Validate MCP protocol version compatibility

Type Aliases§

CommonResult: Common result type for backend implementations
McpResult: Preferred result type alias that doesn’t conflict with std::result::Result
Result: Result type alias for MCP protocol operations

Crate pulseengine_mcp_serverCopy item path