mcpkit-core 0.6.0

//! # mcp-core
//!
//! Core types and traits for the Model Context Protocol (MCP) SDK.
//!
//! This crate provides the foundational building blocks for the MCP SDK:
//!
//! - **Protocol types**: JSON-RPC 2.0 request/response/notification types
//! - **MCP types**: Tools, resources, prompts, tasks, content, sampling, elicitation
//! - **Capability negotiation**: Client and server capabilities
//! - **Error handling**: Unified `McpError` type with rich diagnostics
//! - **Typestate connection**: Compile-time enforced connection lifecycle
//!
//! This crate is runtime-agnostic and does not depend on any async runtime.
//! It can be used with Tokio, smol, or any other executor.
//!
//! # Protocol Version
//!
//! This crate implements MCP protocol version **2025-11-25**.
//!
//! # Example
//!
//! ```rust
//! use mcpkit_core::{
//!     types::{Tool, ToolOutput, Content},
//!     capability::{ServerCapabilities, ServerInfo},
//!     state::Connection,
//! };
//!
//! // Create a tool definition
//! let tool = Tool::new("search")
//!     .description("Search the database")
//!     .input_schema(serde_json::json!({
//!         "type": "object",
//!         "properties": {
//!             "query": { "type": "string" }
//!         },
//!         "required": ["query"]
//!     }));
//!
//! // Create server capabilities
//! let caps = ServerCapabilities::new()
//!     .with_tools()
//!     .with_resources()
//!     .with_tasks();
//!
//! // Create server info
//! let info = ServerInfo::new("my-server", "1.0.0");
//! ```
//!
//! # Feature Flags
//!
//! - **`fancy-errors`**: Enable miette's fancy error reporting with terminal
//!   colors and formatting.
//!
//! - **`jwt`**: Enable JWT validation helpers with JWKS fetching. This adds
//!   the `auth::jwt` module with functions for validating JWT access tokens
//!   and fetching JSON Web Key Sets from authorization servers.

#![deny(missing_docs)]

pub mod auth;
pub mod capability;
pub mod debug;
pub mod error;
pub mod extension;
pub mod protocol;
pub mod protocol_version;
pub mod schema;
pub mod state;
pub mod types;

// Re-export commonly used types at the crate root
pub use capability::{
    ClientCapabilities, ClientInfo, InitializeRequest, InitializeResult, PROTOCOL_VERSION,
    SUPPORTED_PROTOCOL_VERSIONS, ServerCapabilities, ServerInfo, VersionNegotiationResult,
    is_version_supported, negotiate_version, negotiate_version_detailed,
};
pub use error::{JsonRpcError, McpError, McpResultExt};
pub use protocol::{Message, Notification, ProgressToken, Request, RequestId, Response};
pub use protocol_version::ProtocolVersion;
pub use state::{Closing, Connected, Connection, Disconnected, Initializing, Ready};

/// Prelude module for convenient imports.
///
/// # Example
///
/// ```rust
/// use mcpkit_core::prelude::*;
/// ```
pub mod prelude {
    // Re-export common serde types for convenience
    pub use serde::{Deserialize, Serialize};
    pub use serde_json::json;

    pub use crate::capability::{
        ClientCapabilities, ClientInfo, InitializeRequest, InitializeResult, PROTOCOL_VERSION,
        SUPPORTED_PROTOCOL_VERSIONS, ServerCapabilities, ServerInfo, VersionNegotiationResult,
        is_version_supported, negotiate_version, negotiate_version_detailed,
    };
    pub use crate::error::{McpError, McpResultExt};
    pub use crate::protocol::{Message, Notification, ProgressToken, Request, RequestId, Response};
    pub use crate::protocol_version::ProtocolVersion;
    pub use crate::schema::{Schema, SchemaBuilder, SchemaType};
    pub use crate::state::{Closing, Connected, Connection, Disconnected, Initializing, Ready};
    pub use crate::types::{
        // Tool types
        CallToolResult,
        // Content types
        Content,
        ContentAnnotations,
        // Sampling types
        CreateMessageRequest,
        CreateMessageResult,
        // Elicitation types
        ElicitAction,
        ElicitRequest,
        ElicitResult,
        ElicitationSchema,
        // Prompt types
        GetPromptResult,
        ModelPreferences,
        Prompt,
        PromptArgument,
        PromptMessage,
        PromptOutput,
        PropertySchema,
        // Resource types
        Resource,
        ResourceContents,
        ResourceTemplate,
        Role,
        SamplingMessage,
        StopReason,
        // Task types
        Task,
        TaskError,
        TaskId,
        TaskProgress,
        TaskStatus,
        TaskSummary,
        Tool,
        ToolAnnotations,
        ToolOutput,
    };
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_prelude_imports() {
        use crate::prelude::*;

        // Just verify that all the types are accessible
        let _tool = Tool::new("test");
        let _caps = ServerCapabilities::new().with_tools();
        let _conn: Connection<Disconnected> = Connection::new();
    }

    #[test]
    fn test_protocol_version() {
        assert_eq!(PROTOCOL_VERSION, "2025-11-25");
    }

    #[test]
    fn test_error_context() {
        use crate::error::McpResultExt;

        fn might_fail() -> Result<(), McpError> {
            Err(McpError::InternalMessage {
                message: "something went wrong".to_string(),
            })
        }

        let result = might_fail().context("while doing something important");
        assert!(result.is_err());

        let err = result.unwrap_err();
        assert!(err.to_string().contains("while doing something important"));
    }
}