prism_mcp_rs/protocol/
mod.rs

1//! Dual-era MCP protocol implementation.
2//!
3//! This module contains the core protocol types and message handling for the
4//! Model Context Protocol revisions 2026-07-28 and 2025-11-25, including
5//! JSON-RPC serialization, validation, stateless request envelopes, safe
6//! revision selection, and typed protocol objects.
7//!
8//! # Protocol Structure
9//!
10//! The MCP protocol is built on JSON-RPC 2.0 with extensions for:
11//! - **Bidirectional Communication**: Both client and server can send requests
12//! - **Capability Negotiation**: Dynamic feature discovery
13//! - **Content Types**: Rich content including text, images, and resources
14//! - **Batch Operations**: Efficient bulk request processing
15//!
16//! # Core Types
17//!
18//! ## JSON-RPC Messages
19//! ```
20//! use prism_mcp_rs::protocol::{
21//!     JsonRpcRequest, JsonRpcResponse, JsonRpcError, JsonRpcMessage
22//! };
23//! use serde_json::json;
24//!
25//! // Create a request
26//! let request = JsonRpcRequest::new(
27//!     json!("1"),
28//!     "tools/list".to_string(),
29//!     None::<()>,
30//! ).unwrap();
31//!
32//! // Create a success response
33//! let response = JsonRpcResponse::success_unchecked(
34//!     json!("1"),
35//!     json!({"tools": []}),
36//! );
37//!
38//! // Create an error response
39//! let error = JsonRpcError::method_not_found(json!("1"));
40//! ```
41//!
42//! ## Error Handling
43//! ```
44//! use prism_mcp_rs::protocol::{JsonRpcError, error_codes};
45//! use serde_json::json;
46//!
47//! // Standard JSON-RPC errors
48//! let parse_err = JsonRpcError::parse_error(json!(null));
49//! let method_err = JsonRpcError::method_not_found(json!("1"));
50//! let invalid_params = JsonRpcError::invalid_params(json!("1"));
51//!
52//! // MCP-specific errors
53//! let tool_err = JsonRpcError::tool_not_found(json!("1"), "unknown-tool");
54//! let resource_err = JsonRpcError::resource_not_found(json!("1"), "missing.txt");
55//!
56//! // Custom errors with error codes
57//! let custom_err = JsonRpcError::new(
58//!     json!("1"),
59//!     error_codes::INTERNAL_ERROR,
60//!     "Internal server error".to_string()
61//! );
62//! ```
63//!
64//! # Protocol Flow
65//!
66//! - **2026-07-28**: the client sends `server/discover`, then includes its
67//!   revision, identity, and capabilities in every request `_meta` object.
68//! - **2025-11-25**: the client performs `initialize`, retains negotiated
69//!   connection state, and sends the initialized notification.
70//!
71//! [`ProtocolMode::Auto`] prefers 2026 and permits a 2025 fallback only when
72//! `server/discover` is explicitly rejected as an unknown method.
73//!
74//! # Features
75//!
76//! - **Type Safety**: Strongly typed protocol messages
77//! - **Validation**: Request and response validation
78//! - **Extensibility**: Support for custom methods and capabilities
79//! - **Batch Processing**: Efficient bulk operations
80//! - **Metadata**: Rich metadata for all protocol objects
81
82pub mod batch;
83pub mod discovery;
84pub mod error_helpers;
85pub mod messages;
86pub mod metadata;
87pub mod methods;
88pub mod missing_types;
89pub mod roots_types;
90pub mod schema_introspection;
91pub mod subscriptions;
92pub mod tasks;
93pub mod types;
94pub mod validation;
95pub mod version;
96
97// Re-export commonly used types and constants
98pub use batch::*;
99pub use discovery::*;
100pub use error_helpers::IntoJsonRpcMessage;
101pub use messages::*;
102
103// Re-export metadata module types (Implementation is now only in types module)
104pub use metadata::{MetadataBuilder, ProtocolCapabilities};
105
106pub use missing_types::*;
107// Re-export roots_types items except those that conflict with messages
108pub use roots_types::{
109    ListRootsRequest,
110    RootsListChangedNotification,
111    // Explicitly exclude Root and ListRootsResult which are already in messages
112};
113pub use schema_introspection::*;
114pub use subscriptions::*;
115pub use tasks::*;
116// Re-export all types module items
117pub use types::{
118    error_codes, AnnotationAudience, Annotations, AudioContent, BaseMetadata, CallToolResult,
119    ClientCapabilities, ClientInfo, CompletionsCapability, Content, ContentBlock,
120    CreateMessageResult, Cursor, DangerLevel, ElicitationAction, ElicitationCapability,
121    ElicitationSchema, EmbeddedResource, ErrorObject, GetPromptResult, Icon, IconTheme,
122    ImageContent, Implementation, JsonRpcBatchRequest, JsonRpcBatchResponse, JsonRpcError,
123    JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcRequestOrNotification,
124    JsonRpcResponse, JsonRpcResponseOrError, LoggingCapability, LoggingLevel, ModelHint,
125    ModelPreferences, Notification, NotificationParams, PaginatedRequest, PaginatedResult,
126    PrimitiveSchemaDefinition, ProgressToken, Prompt, PromptArgument, PromptInfo, PromptMessage,
127    PromptResult, PromptsCapability, Request, RequestId, RequestMeta, RequestParams, Resource,
128    ResourceContents, ResourceInfo, ResourceLink, ResourceTemplate, ResourcesCapability, Role,
129    RootsCapability, SamplingCapability, SamplingContent, SamplingMessage, SamplingToolChoice,
130    ServerCapabilities, ServerInfo, StopReason, TextContent, Tool, ToolAnnotations, ToolInfo,
131    ToolInputSchema, ToolOutputSchema, ToolResult, ToolsCapability, JSONRPC_VERSION,
132    LATEST_PROTOCOL_VERSION, PROTOCOL_VERSION,
133};
134
135pub use validation::*;
136pub use version::{
137    decode_http_header_value, decorate_modern_request, decorate_modern_result,
138    encode_http_header_value, is_cacheable_method, is_legacy_only_method, is_method_not_found,
139    json_rpc_error_details, modern_request_context, request_protocol_version, request_routing_name,
140    tool_call_headers, tool_header_mappings, validate_http_headers, validate_tool_call_headers,
141    CacheScope, ConnectResult, DiscoverParams, DiscoverResult as ModernDiscoverResult,
142    InputRequiredResult, ModernRequestContext, NegotiatedProtocol, OperationResult, ProtocolEra,
143    ProtocolMode, RequestMetaObject, ResultType, ToolHeaderMapping, CLIENT_CAPABILITIES_META_KEY,
144    CLIENT_INFO_META_KEY, HEADER_MISMATCH, LEGACY_PROTOCOL_VERSION, MCP_METHOD_HEADER,
145    MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MISSING_REQUIRED_CLIENT_CAPABILITY,
146    MODERN_PROTOCOL_VERSION, PROTOCOL_VERSION_META_KEY, SERVER_INFO_META_KEY,
147    SUPPORTED_PROTOCOL_VERSIONS, UNSUPPORTED_PROTOCOL_VERSION,
148};
149
150// Re-export method constants for convenience
151pub use methods::{
152    CANCELLED, COMPLETION_COMPLETE, ELICITATION_COMPLETE, INITIALIZE, INITIALIZED, LOGGING_MESSAGE,
153    LOGGING_SET_LEVEL, PING, PROGRESS, PROMPTS_GET, PROMPTS_LIST, PROMPTS_LIST_CHANGED,
154    RESOURCES_LIST, RESOURCES_LIST_CHANGED, RESOURCES_READ, RESOURCES_SUBSCRIBE,
155    RESOURCES_TEMPLATES_LIST, RESOURCES_UNSUBSCRIBE, RESOURCES_UPDATED, ROOTS_LIST,
156    ROOTS_LIST_CHANGED, RPC_DISCOVER, SAMPLING_CREATE_MESSAGE, SERVER_DISCOVER,
157    SUBSCRIPTIONS_ACKNOWLEDGED, SUBSCRIPTIONS_LISTEN, TASKS_CANCEL, TASKS_GET, TASKS_SEND,
158    TASKS_STATUS, TASKS_STATUS_UPDATE, TASKS_UPDATE, TOOLS_CALL, TOOLS_LIST, TOOLS_LIST_CHANGED,
159};
160
161// Legacy constant for compatibility
162pub const MCP_PROTOCOL_VERSION: &str = LATEST_PROTOCOL_VERSION;
prism_mcp_rs/protocol/mod.rs

prism_mcp_rs/protocol/
mod.rs
