prism_mcp_rs/core/
mod.rs

1//! Core abstractions and types for the MCP SDK
2//!
3//! This module contains the fundamental building blocks for MCP implementations,
4//! including error handling, resource management, tool execution, and prompt handling.
5//!
6//! # Core Concepts
7//!
8//! ## Tools
9//! Tools represent executable functions that can be called by the MCP protocol:
10//!
11
12//! ```
13//! use prism_mcp_rs::core::{Tool, ToolBuilder, ToolHandler};
14//! use prism_mcp_rs::core::error::{McpError, McpResult};
15//! use std::collections::HashMap;
16//! use prism_mcp_rs::protocol::types::{ToolInfo, ToolResult, ContentBlock};
17//! use serde_json::{json, Value};
18//! use async_trait::async_trait;
19//!
20//! struct CalculatorTool;
21//!
22//! #[async_trait]
23//! impl ToolHandler for CalculatorTool {
24//!     async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
25//!         // Tool implementation  
26//!         Ok(ToolResult {
27//!             content: vec![ContentBlock::Text {
28//!                 text: "Result: 42".to_string(),
29//!                 annotations: None,
30//!                 meta: None,
31//!             }],
32//!             is_error: Some(false),
33//!             meta: None,
34//!             structured_content: None,
35//!         })
36//!     }
37//! }
38//!
39//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
40//! // Build the tool with the handler
41//! let tool = ToolBuilder::new("calculator")
42//!     .description("Performs calculations")
43//!     .build(CalculatorTool)?;
44//! # Ok(())
45//! # }
46//! ```
47
48//!
49//! ## Resources
50//! Resources provide access to external data sources:
51//!
52//! ```
53//! use prism_mcp_rs::core::{Resource, ResourceHandler};
54//! use prism_mcp_rs::core::error::McpResult;
55//! use std::collections::HashMap;
56//! use prism_mcp_rs::protocol::types::{ResourceContents, ContentBlock};
57//! use prism_mcp_rs::core::{ResourceInfo};
58//! use async_trait::async_trait;
59//!
60//! struct FileResource;
61//!
62//! #[async_trait]
63//! impl ResourceHandler for FileResource {
64//!     async fn read(
65//!         &self,
66//!         uri: &str,
67//!         params: &HashMap<String, String>,
68//!     ) -> McpResult<Vec<ResourceContents>> {
69//!         Ok(vec![ResourceContents::Text {
70//!             uri: uri.to_string(),
71//!             mime_type: Some("text/plain".to_string()),
72//!             text: "File contents".to_string(),
73//!             meta: None,
74//!         }])
75//!     }
76//!     
77//!     async fn list(&self) -> McpResult<Vec<ResourceInfo>> {
78//!         Ok(vec![])
79//!     }
80//! }
81//! ```
82//!
83//! ## Prompts
84//! Prompts provide reusable interaction templates:
85//!
86//! ```
87//! use prism_mcp_rs::core::{Prompt, PromptHandler};
88//! use prism_mcp_rs::core::error::McpResult;
89//! use std::collections::HashMap;
90//! use prism_mcp_rs::protocol::types::{PromptResult, PromptMessage, Role, ContentBlock};
91//! use serde_json::Value;
92//! use async_trait::async_trait;
93//!
94//! struct GreetingPrompt;
95//!
96//! #[async_trait]
97//! impl PromptHandler for GreetingPrompt {
98//!     async fn get(&self, arguments: HashMap<String, Value>) -> McpResult<PromptResult> {
99//!         Ok(PromptResult {
100//!             description: Some("A friendly greeting".to_string()),
101//!             messages: vec![
102//!                 PromptMessage {
103//!                     role: Role::Assistant,
104//!                     content: ContentBlock::Text {
105//!                         text: "Hello! How can I help you today?".to_string(),
106//!                         annotations: None,
107//!                         meta: None,
108//!                     },
109//!                 }
110//!             ],
111//!             meta: None,
112//!         })
113//!     }
114//! }
115//! ```
116//!
117//! ## Error Handling
118//! The SDK provides comprehensive error handling:
119//!
120//! ```
121//! use prism_mcp_rs::core::{McpError, McpResult};
122//!
123//! fn process_data() -> McpResult<String> {
124//!     // Return errors using the ? operator
125//!     let data = std::fs::read_to_string("data.txt")
126//!         .map_err(|e| McpError::Io(e.to_string()))?;
127//!     
128//!     Ok(data)
129//! }
130//! ```
131//!
132//! # Features
133//!
134//! - **Type-Safe Handlers**: Strongly typed handler traits
135//! - **Async Support**: All handlers are async by default
136//! - **Builder Patterns**: Ergonomic construction APIs
137//! - **Validation**: Built-in parameter validation
138//! - **Discovery**: Tool discovery and metadata support
139
140pub mod completion;
141pub mod completion_handlers;
142pub mod enhanced_errors;
143pub mod error;
144pub mod health;
145pub mod logging;
146pub mod metrics;
147pub mod prompt;
148pub mod resource;
149pub mod retry;
150pub mod tool;
151pub mod tool_discovery;
152pub mod tool_metadata;
153pub mod validation;
154
155// Re-export commonly used items
156pub use completion::{
157    CompletionContext, CompletionHandler, CompositeCompletionHandler, PromptCompletionHandler,
158    ResourceUriCompletionHandler, ToolCompletionHandler,
159};
160pub use completion_handlers::{
161    CompositeCompletionHandler as ExtendedCompositeCompletionHandler, FileSystemCompletionHandler,
162    FuzzyCompletionHandler, SchemaCompletionHandler,
163};
164pub use error::{McpError, McpResult};
165pub use prompt::{Prompt, PromptHandler};
166pub use resource::{Resource, ResourceHandler, ResourceTemplate};
167pub use tool::{MultiRoundToolCall, MultiRoundToolHandler, Tool, ToolBuilder, ToolHandler};
168pub use tool_discovery::{
169    DeprecationCleanupPolicy, DiscoveryCriteria, DiscoveryResult, GlobalToolStats, ToolRegistry,
170};
171pub use tool_metadata::{
172    CategoryFilter, DeprecationSeverity, ImprovedToolMetadata, ToolBehaviorHints, ToolCategory,
173    ToolDeprecation,
174};
175pub use validation::{ParameterType, ParameterValidator, ValidationConfig};
176
177// Re-export protocol types through core for convenience
178pub use crate::protocol::types::{
179    PromptArgument, PromptInfo, PromptMessage, PromptResult, ResourceInfo, ToolInfo,
180};
prism_mcp_rs/core/mod.rs

prism_mcp_rs/core/
mod.rs
