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

mcpkit_core/
lib.rs
