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, async-std, 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 error;
60pub mod protocol;
61pub mod protocol_version;
62pub mod schema;
63pub mod state;
64pub mod types;
65
66// Re-export commonly used types at the crate root
67pub use capability::{
68    is_version_supported, negotiate_version, negotiate_version_detailed, ClientCapabilities,
69    ClientInfo, InitializeRequest, InitializeResult, ServerCapabilities, ServerInfo,
70    VersionNegotiationResult, PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS,
71};
72pub use error::{JsonRpcError, McpError, McpResultExt};
73pub use protocol::{Message, Notification, ProgressToken, Request, RequestId, Response};
74pub use protocol_version::ProtocolVersion;
75pub use state::{Closing, Connected, Connection, Disconnected, Initializing, Ready};
76
77/// Prelude module for convenient imports.
78///
79/// # Example
80///
81/// ```rust
82/// use mcpkit_core::prelude::*;
83/// ```
84pub mod prelude {
85    pub use crate::capability::{
86        is_version_supported, negotiate_version, negotiate_version_detailed, ClientCapabilities,
87        ClientInfo, InitializeRequest, InitializeResult, ServerCapabilities, ServerInfo,
88        VersionNegotiationResult, PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS,
89    };
90    pub use crate::error::{McpError, McpResultExt};
91    pub use crate::protocol::{Message, Notification, ProgressToken, Request, RequestId, Response};
92    pub use crate::protocol_version::ProtocolVersion;
93    pub use crate::schema::{Schema, SchemaBuilder, SchemaType};
94    pub use crate::state::{Closing, Connected, Connection, Disconnected, Initializing, Ready};
95    pub use crate::types::{
96        // Tool types
97        CallToolResult,
98        // Content types
99        Content,
100        ContentAnnotations,
101        // Sampling types
102        CreateMessageRequest,
103        CreateMessageResult,
104        // Elicitation types
105        ElicitAction,
106        ElicitRequest,
107        ElicitResult,
108        ElicitationSchema,
109        // Prompt types
110        GetPromptResult,
111        ModelPreferences,
112        Prompt,
113        PromptArgument,
114        PromptMessage,
115        PromptOutput,
116        PropertySchema,
117        // Resource types
118        Resource,
119        ResourceContents,
120        ResourceTemplate,
121        Role,
122        SamplingMessage,
123        StopReason,
124        // Task types
125        Task,
126        TaskError,
127        TaskId,
128        TaskProgress,
129        TaskStatus,
130        TaskSummary,
131        Tool,
132        ToolAnnotations,
133        ToolOutput,
134    };
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140
141    #[test]
142    fn test_prelude_imports() {
143        use crate::prelude::*;
144
145        // Just verify that all the types are accessible
146        let _tool = Tool::new("test");
147        let _caps = ServerCapabilities::new().with_tools();
148        let _conn: Connection<Disconnected> = Connection::new();
149    }
150
151    #[test]
152    fn test_protocol_version() {
153        assert_eq!(PROTOCOL_VERSION, "2025-11-25");
154    }
155
156    #[test]
157    fn test_error_context() {
158        use crate::error::McpResultExt;
159
160        fn might_fail() -> Result<(), McpError> {
161            Err(McpError::InternalMessage {
162                message: "something went wrong".to_string(),
163            })
164        }
165
166        let result = might_fail().context("while doing something important");
167        assert!(result.is_err());
168
169        let err = result.unwrap_err();
170        assert!(err.to_string().contains("while doing something important"));
171    }
172}
mcpkit_core/lib.rs

mcpkit_core/
lib.rs
