mcpkit_core/
lib.rs

1//! # mcp-core
2//!
3//! Core types and traits for the Model Context Protocol (MCP) SDK.
4//!
5//! This crate provides the foundational building blocks for the MCP SDK:
6//!
7//! - **Protocol types**: JSON-RPC 2.0 request/response/notification types
8//! - **MCP types**: Tools, resources, prompts, tasks, content, sampling, elicitation
9//! - **Capability negotiation**: Client and server capabilities
10//! - **Error handling**: Unified `McpError` type with rich diagnostics
11//! - **Typestate connection**: Compile-time enforced connection lifecycle
12//!
13//! This crate is runtime-agnostic and does not depend on any async runtime.
14//! It can be used with Tokio, smol, or any other executor.
15//!
16//! # Protocol Version
17//!
18//! This crate implements MCP protocol version **2025-11-25**.
19//!
20//! # Example
21//!
22//! ```rust
23//! use mcpkit_core::{
24//!     types::{Tool, ToolOutput, Content},
25//!     capability::{ServerCapabilities, ServerInfo},
26//!     state::Connection,
27//! };
28//!
29//! // Create a tool definition
30//! let tool = Tool::new("search")
31//!     .description("Search the database")
32//!     .input_schema(serde_json::json!({
33//!         "type": "object",
34//!         "properties": {
35//!             "query": { "type": "string" }
36//!         },
37//!         "required": ["query"]
38//!     }));
39//!
40//! // Create server capabilities
41//! let caps = ServerCapabilities::new()
42//!     .with_tools()
43//!     .with_resources()
44//!     .with_tasks();
45//!
46//! // Create server info
47//! let info = ServerInfo::new("my-server", "1.0.0");
48//! ```
49//!
50//! # Feature Flags
51//!
52//! This crate currently has no optional features. All functionality is
53//! included by default.
54
55#![deny(missing_docs)]
56
57pub mod auth;
58pub mod capability;
59pub mod debug;
60pub mod error;
61pub mod extension;
62pub mod protocol;
63pub mod protocol_version;
64pub mod schema;
65pub mod state;
66pub mod types;
67
68// Re-export commonly used types at the crate root
69pub use capability::{
70    ClientCapabilities, ClientInfo, InitializeRequest, InitializeResult, PROTOCOL_VERSION,
71    SUPPORTED_PROTOCOL_VERSIONS, ServerCapabilities, ServerInfo, VersionNegotiationResult,
72    is_version_supported, negotiate_version, negotiate_version_detailed,
73};
74pub use error::{JsonRpcError, McpError, McpResultExt};
75pub use protocol::{Message, Notification, ProgressToken, Request, RequestId, Response};
76pub use protocol_version::ProtocolVersion;
77pub use state::{Closing, Connected, Connection, Disconnected, Initializing, Ready};
78
79/// Prelude module for convenient imports.
80///
81/// # Example
82///
83/// ```rust
84/// use mcpkit_core::prelude::*;
85/// ```
86pub mod prelude {
87    // Re-export common serde types for convenience
88    pub use serde::{Deserialize, Serialize};
89    pub use serde_json::json;
90
91    pub use crate::capability::{
92        ClientCapabilities, ClientInfo, InitializeRequest, InitializeResult, PROTOCOL_VERSION,
93        SUPPORTED_PROTOCOL_VERSIONS, ServerCapabilities, ServerInfo, VersionNegotiationResult,
94        is_version_supported, negotiate_version, negotiate_version_detailed,
95    };
96    pub use crate::error::{McpError, McpResultExt};
97    pub use crate::protocol::{Message, Notification, ProgressToken, Request, RequestId, Response};
98    pub use crate::protocol_version::ProtocolVersion;
99    pub use crate::schema::{Schema, SchemaBuilder, SchemaType};
100    pub use crate::state::{Closing, Connected, Connection, Disconnected, Initializing, Ready};
101    pub use crate::types::{
102        // Tool types
103        CallToolResult,
104        // Content types
105        Content,
106        ContentAnnotations,
107        // Sampling types
108        CreateMessageRequest,
109        CreateMessageResult,
110        // Elicitation types
111        ElicitAction,
112        ElicitRequest,
113        ElicitResult,
114        ElicitationSchema,
115        // Prompt types
116        GetPromptResult,
117        ModelPreferences,
118        Prompt,
119        PromptArgument,
120        PromptMessage,
121        PromptOutput,
122        PropertySchema,
123        // Resource types
124        Resource,
125        ResourceContents,
126        ResourceTemplate,
127        Role,
128        SamplingMessage,
129        StopReason,
130        // Task types
131        Task,
132        TaskError,
133        TaskId,
134        TaskProgress,
135        TaskStatus,
136        TaskSummary,
137        Tool,
138        ToolAnnotations,
139        ToolOutput,
140    };
141}
142
143#[cfg(test)]
144mod tests {
145    use super::*;
146
147    #[test]
148    fn test_prelude_imports() {
149        use crate::prelude::*;
150
151        // Just verify that all the types are accessible
152        let _tool = Tool::new("test");
153        let _caps = ServerCapabilities::new().with_tools();
154        let _conn: Connection<Disconnected> = Connection::new();
155    }
156
157    #[test]
158    fn test_protocol_version() {
159        assert_eq!(PROTOCOL_VERSION, "2025-11-25");
160    }
161
162    #[test]
163    fn test_error_context() {
164        use crate::error::McpResultExt;
165
166        fn might_fail() -> Result<(), McpError> {
167            Err(McpError::InternalMessage {
168                message: "something went wrong".to_string(),
169            })
170        }
171
172        let result = might_fail().context("while doing something important");
173        assert!(result.is_err());
174
175        let err = result.unwrap_err();
176        assert!(err.to_string().contains("while doing something important"));
177    }
178}
mcpkit_core/lib.rs

mcpkit_core/
lib.rs
