prism_mcp_rs/
lib.rs

1// Copyright (c) 2025 Prismworks AI Inc.
2// SPDX-License-Identifier: MIT
3
4//! # Prism MCP Rust SDK
5//!
6//! Async client and server primitives for the
7//! [Model Context Protocol](https://modelcontextprotocol.io/) 2026-07-28 with
8//! interoperable 2025-11-25 support.
9//! The crate includes protocol types, tools, resources, prompts, sampling,
10//! completion, roots, replaceable transports, and opt-in production controls.
11//!
12//! STDIO is enabled by default. HTTP, WebSocket, SSE, authentication helpers,
13//! TLS/mTLS, OpenTelemetry, compression, and trusted native plugins are
14//! feature-gated. Security controls are not enabled automatically: a host must
15//! authenticate callers and install its request policy.
16//!
17//! ## Quick Start
18//!
19//! The easiest way to get started is with the prelude module:
20//!
21//! ```rust
22//! use prism_mcp_rs::prelude::*;
23//! ```
24//!
25//! This imports all the commonly used types and traits.
26//!
27//! ### Server Example
28//!
29//! ```rust,no_run
30//! use prism_mcp_rs::prelude::*;
31//! use std::collections::HashMap;
32//!
33//! struct EchoHandler;
34//!
35//! #[async_trait]
36//! impl ToolHandler for EchoHandler {
37//!     async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
38//!         let message = arguments.get("message")
39//!             .and_then(|v| v.as_str())
40//!             .unwrap_or_default();
41//!
42//!         Ok(ToolResult {
43//!             content: vec![ContentBlock::text(message)],
44//!             is_error: Some(false),
45//!             structured_content: None,
46//!             meta: None,
47//!         })
48//!     }
49//! }
50//!
51//! # #[cfg(feature = "stdio")]
52//! #[tokio::main]
53//! async fn main() -> McpResult<()> {
54//!     let server = McpServer::create("echo-server", "1.0.0");
55//!
56//!     server.add_tool(
57//!         "echo",
58//!         Some("Echo a message"),
59//!         json!({
60//!             "type": "object",
61//!             "properties": {
62//!                 "message": { "type": "string" }
63//!             }
64//!         }),
65//!         EchoHandler,
66//!     ).await?;
67//!
68//!     server.run_with_transport(StdioServerTransport::new()).await
69//! }
70//! # #[cfg(not(feature = "stdio"))]
71//! # fn main() {}
72//! ```
73//!
74//! ## Module Organization
75//!
76//! - [`core`]: Core abstractions for resources, tools, prompts, and errors
77//! - `plugin`: trusted native dynamic tool loading (feature-gated)
78//! - [`protocol`]: MCP 2026/2025 types, negotiation, and message definitions
79//! - [`transport`]: Transport layer implementations (STDIO, HTTP, WebSocket)
80//! - [`server`]: MCP server implementation and lifecycle management
81//! - [`client`]: MCP client implementation and session management
82//! - [`security`]: request identity, authorization, and rate limiting
83//! - [`utils`]: utility functions and helpers
84
85#[cfg(feature = "http")]
86pub mod auth;
87pub mod client;
88pub mod core;
89#[cfg(feature = "plugin")]
90pub mod plugin;
91pub mod protocol;
92pub mod security;
93pub mod server;
94#[cfg(feature = "otel")]
95pub mod telemetry;
96pub mod transport;
97pub mod utils;
98
99// Re-export commonly used types for convenience
100pub use core::error::{McpError, McpResult};
101pub use protocol::types::*;
102pub use protocol::{
103    ErrorObject, JsonRpcError, JsonRpcMessage, JsonRpcRequest, JsonRpcResponse, ServerCapabilities,
104};
105
106/// Prelude module for convenient imports
107///
108/// Module re-exports the most commonly used types and traits for easy access.
109/// Use `use prism_mcp_rs::prelude::*;` to import everything you need.
110pub mod prelude {
111    // Core types and traits
112    pub use crate::core::{
113        error::{McpError, McpResult},
114        prompt::{Prompt, PromptHandler},
115        resource::{Resource, ResourceHandler},
116        tool::{MultiRoundToolCall, MultiRoundToolHandler, Tool, ToolHandler},
117    };
118    pub use crate::security::{
119        Permission, Principal, RateLimitConfig, RateLimiter, RbacAuthorizer, RequestContext,
120        RequestPolicy, RequestTarget,
121    };
122
123    // Protocol types and messages
124    pub use crate::protocol::error_codes;
125    pub use crate::protocol::error_helpers::IntoJsonRpcMessage;
126    pub use crate::protocol::messages::*;
127    pub use crate::protocol::missing_types::*;
128    pub use crate::protocol::types::*;
129    pub use crate::protocol::{
130        ConnectResult, NegotiatedProtocol, ProtocolEra, ProtocolMode, LEGACY_PROTOCOL_VERSION,
131        MODERN_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS,
132    };
133
134    // Client and completion handlers
135    pub use crate::client::{
136        AutomatedClientRequestHandler, ClientRequestHandler, InteractiveClientRequestHandler,
137    };
138    pub use crate::core::completion::{
139        CompletionHandler, PromptCompletionHandler, ResourceUriCompletionHandler,
140    };
141    pub use crate::core::completion_handlers::{
142        CompositeCompletionHandler as ExtendedCompositeCompletionHandler,
143        FileSystemCompletionHandler, FuzzyCompletionHandler, SchemaCompletionHandler,
144    };
145
146    // Server and Client
147    pub use crate::client::McpClient;
148    pub use crate::server::{McpServer, ServerBuilder, ServerConfig};
149
150    // Transport layer implementations
151    #[cfg(feature = "stdio")]
152    pub use crate::transport::{StdioClientTransport, StdioServerTransport};
153
154    #[cfg(feature = "http")]
155    pub use crate::transport::{HttpClientTransport, HttpServerTransport};
156
157    #[cfg(feature = "websocket")]
158    pub use crate::transport::{WebSocketClientTransport, WebSocketServerTransport};
159
160    pub use crate::transport::{EndpointPoolConfig, EndpointPoolTransport};
161
162    // Plugin system
163    #[cfg(feature = "plugin")]
164    pub use crate::plugin::{LoadResult, LoadedPluginInfo, PluginManager};
165
166    // Core builders
167    pub use crate::core::prompt::PromptBuilder;
168    pub use crate::core::resource::ResourceBuilder;
169    pub use crate::core::tool::ToolBuilder;
170
171    // Essential external types
172    pub use async_trait::async_trait;
173    pub use serde_json::{json, Value};
174    pub use std::collections::HashMap;
175}
176
177// Testing utilities (only available in tests)
178#[cfg(test)]
179pub mod test_utils;
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    #[test]
186    fn test_library_exports() {
187        // Basic smoke test to ensure all modules are accessible
188        let _error = McpError::Protocol("test".to_string());
189    }
190}
prism_mcp_rs/lib.rs

prism_mcp_rs/
lib.rs
