pulseengine_mcp_server/
lib.rs

1//! Generic MCP server infrastructure with pluggable backends
2//!
3//! This crate provides a complete MCP server implementation that can be extended
4//! with custom backends for different domains (home automation, databases, APIs, etc.).
5//!
6//! # Quick Start
7//!
8//! ```rust,ignore
9//! use pulseengine_mcp_server::{McpServer, McpBackend, ServerConfig};
10//! use pulseengine_mcp_protocol::*;
11//! use async_trait::async_trait;
12//!
13//! #[derive(Clone)]
14//! struct MyBackend;
15//!
16//! #[async_trait]
17//! impl McpBackend for MyBackend {
18//!     type Error = Box<dyn std::error::Error + Send + Sync>;
19//!     type Config = ();
20//!
21//!     async fn initialize(_: ()) -> std::result::Result<Self, Self::Error> {
22//!         Ok(MyBackend)
23//!     }
24//!
25//!     fn get_server_info(&self) -> ServerInfo {
26//!         ServerInfo {
27//!             protocol_version: ProtocolVersion::default(),
28//!             capabilities: ServerCapabilities::default(),
29//!             server_info: Implementation {
30//!                 name: "My Server".to_string(),
31//!                 version: "1.0.0".to_string(),
32//!             },
33//!             instructions: Some("Example server".to_string()),
34//!         }
35//!     }
36//!
37//!     async fn list_tools(&self, _: PaginatedRequestParam) -> std::result::Result<ListToolsResult, Self::Error> {
38//!         Ok(ListToolsResult { tools: vec![], next_cursor: None })
39//!     }
40//!
41//!     async fn call_tool(&self, _: CallToolRequestParam) -> Result<CallToolResult, Self::Error> {
42//!         Ok(CallToolResult { content: vec![], is_error: Some(false) })
43//!     }
44//!
45//!     // Implement other required methods (simplified for example)
46//! #   async fn list_resources(&self, _: PaginatedRequestParam) -> Result<ListResourcesResult, Self::Error> {
47//! #       Ok(ListResourcesResult { resources: vec![], next_cursor: String::new() })
48//! #   }
49//! #   async fn read_resource(&self, _: ReadResourceRequestParam) -> Result<ReadResourceResult, Self::Error> {
50//! #       Err("No resources".into())
51//! #   }
52//! #   async fn list_prompts(&self, _: PaginatedRequestParam) -> Result<ListPromptsResult, Self::Error> {
53//! #       Ok(ListPromptsResult { prompts: vec![], next_cursor: String::new() })
54//! #   }
55//! #   async fn get_prompt(&self, _: GetPromptRequestParam) -> Result<GetPromptResult, Self::Error> {
56//! #       Err("No prompts".into())
57//! #   }
58//! }
59//!
60//! #[tokio::main]
61//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
62//!     let backend = MyBackend::initialize(()).await?;
63//!     let config = ServerConfig::default();
64//!     let mut server = McpServer::new(backend, config).await?;
65//!     server.run().await?;
66//!     Ok(())
67//! }
68//! ```
69//!
70//! # Authentication Options
71//!
72//! The server supports multiple authentication backends for different deployment scenarios:
73//!
74//! ## File-based Authentication (Default)
75//!
76//! ```rust,ignore
77//! use pulseengine_mcp_server::{McpServer, ServerConfig, AuthConfig};
78//! use pulseengine_mcp_auth::config::StorageConfig;
79//! use std::path::PathBuf;
80//!
81//! let auth_config = AuthConfig {
82//!     storage: StorageConfig::File {
83//!         path: PathBuf::from("~/.pulseengine/mcp-auth/keys.enc"),
84//!         file_permissions: 0o600,
85//!         dir_permissions: 0o700,
86//!         require_secure_filesystem: true,
87//!         enable_filesystem_monitoring: false,
88//!     },
89//!     enabled: true,
90//!     // ... other config
91//! };
92//!
93//! let server_config = ServerConfig {
94//!     auth_config: Some(auth_config),
95//!     // ... other config
96//! };
97//! ```
98//!
99//! ## Environment Variable Authentication
100//!
101//! For containerized deployments without filesystem access:
102//!
103//! ```rust,ignore
104//! use pulseengine_mcp_server::{McpServer, ServerConfig, AuthConfig};
105//! use pulseengine_mcp_auth::config::StorageConfig;
106//!
107//! let auth_config = AuthConfig {
108//!     storage: StorageConfig::Environment {
109//!         prefix: "MCP_AUTH".to_string(),
110//!     },
111//!     enabled: true,
112//!     // ... other config
113//! };
114//!
115//! // Set environment variables:
116//! // MCP_AUTH_API_KEY_ADMIN_1=admin-key-12345
117//! // MCP_AUTH_API_KEY_OPERATOR_1=operator-key-67890
118//! ```
119//!
120
121pub mod builder_trait;
122pub mod common_backend;
123
124pub mod backend;
125pub mod context;
126pub mod handler;
127pub mod middleware;
128pub mod server;
129
130// Endpoint modules
131pub mod alerting_endpoint;
132pub mod dashboard_endpoint;
133pub mod health_endpoint;
134pub mod metrics_endpoint;
135
136// Test modules
137#[cfg(test)]
138mod backend_tests;
139#[cfg(test)]
140mod context_tests;
141#[cfg(test)]
142mod handler_tests;
143#[cfg(test)]
144mod lib_tests;
145#[cfg(test)]
146mod middleware_tests;
147#[cfg(test)]
148mod server_tests;
149
150// Re-export core types
151pub use backend::{BackendError, McpBackend};
152pub use builder_trait::{McpServerBuilder, McpService};
153pub use common_backend::{
154    CommonBackendImpl, CommonMcpError, HasServerInfo, McpPromptsProvider, McpResourcesProvider,
155    McpToolsProvider,
156};
157pub use context::RequestContext;
158pub use handler::{GenericServerHandler, HandlerError};
159pub use middleware::{Middleware, MiddlewareStack};
160pub use server::{McpServer, ServerConfig, ServerError};
161
162// Re-export from dependencies for convenience
163pub use pulseengine_mcp_auth::{self as auth, AuthConfig, AuthenticationManager};
164pub use pulseengine_mcp_monitoring::{self as monitoring, MetricsCollector, MonitoringConfig};
165pub use pulseengine_mcp_protocol::{self as protocol, *};
166pub use pulseengine_mcp_security::{self as security, SecurityConfig, SecurityMiddleware};
167pub use pulseengine_mcp_transport::{self as transport, Transport, TransportConfig};
pulseengine_mcp_server/lib.rs

pulseengine_mcp_server/
lib.rs
