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

mcpkit_core/
lib.rs
