mcp_core/
lib.rs

1//! # Model Context Protocol (MCP) Core Library
2//!
3//! `mcp-core` is a Rust implementation of the Model Context Protocol (MCP), an open
4//! protocol for interaction between AI models and tools/external systems.
5//!
6//! This library provides a comprehensive framework for building both MCP servers (tool providers)
7//! and MCP clients (model interfaces), with support for:
8//!
9//! - Bidirectional communication between AI models and external tools
10//! - Tool registration, discovery, and invocation
11//! - Resource management
12//! - Transport-agnostic design (supporting both SSE and stdio)
13//! - Standardized request/response formats using JSON-RPC
14//!
15//! ## Architecture
16//!
17//! The library is organized into several main components:
18//!
19//! - **Client**: Implementation of the MCP client for connecting to servers
20//! - **Server**: Implementation of the MCP server for exposing tools to clients
21//! - **Protocol**: Core protocol implementation using JSON-RPC
22//! - **Types**: Data structures representing MCP concepts
23//! - **Transport**: Network transport abstraction (SSE, stdio)
24//! - **Tools**: Framework for registering and invoking tools
25//!
26//! ## Usage
27//!
28//! For examples of how to use this library, see the `examples/` directory:
29//! - `echo_server.rs`: A simple MCP server implementation
30//! - `echo_server_macro.rs`: Using the `#[tool]` macro for simpler integration
31//! - `echo_client.rs`: A client connecting to an MCP server
32//!
33//! ## Macros
34//!
35//! This library includes a set of utility macros to make working with the MCP protocol
36//! easier, including helpers for creating various types of tool responses.
37
38pub mod client;
39pub mod protocol;
40pub mod server;
41pub mod tools;
42pub mod transport;
43pub mod types;
44
45/// Creates a tool response with error information.
46///
47/// This macro generates a `CallToolResponse` containing a text error message
48/// and sets the `is_error` flag to `true`.
49///
50/// # Examples
51///
52/// ```
53/// use mcp_core::tool_error_response;
54/// use anyhow::Error;
55///
56/// let error = Error::msg("Something went wrong");
57/// let response = tool_error_response!(error);
58/// assert_eq!(response.is_error, Some(true));
59/// ```
60#[macro_export]
61macro_rules! tool_error_response {
62    ($e:expr) => {{
63        let error_message = $e.to_string();
64        $crate::types::CallToolResponse {
65            content: vec![$crate::types::ToolResponseContent::Text(
66                $crate::types::TextContent {
67                    content_type: "text".to_string(),
68                    text: error_message,
69                    annotations: None,
70                },
71            )],
72            is_error: Some(true),
73            meta: None,
74        }
75    }};
76}
77
78/// Creates a tool response with text content.
79///
80/// This macro generates a `CallToolResponse` containing the provided text.
81///
82/// # Examples
83///
84/// ```
85/// use mcp_core::tool_text_response;
86///
87/// let response = tool_text_response!("Hello, world!");
88/// ```
89#[macro_export]
90macro_rules! tool_text_response {
91    ($e:expr) => {{
92        $crate::types::CallToolResponse {
93            content: vec![$crate::types::ToolResponseContent::Text(
94                $crate::types::TextContent {
95                    content_type: "text".to_string(),
96                    text: $e.to_string(),
97                    annotations: None,
98                },
99            )],
100            is_error: None,
101            meta: None,
102        }
103    }};
104}
105
106/// Creates a text content object for tool responses.
107///
108/// This macro generates a `ToolResponseContent::Text` object with the provided text.
109///
110/// # Examples
111///
112/// ```
113/// use mcp_core::tool_text_content;
114///
115/// let content = tool_text_content!("Hello, world!");
116/// ```
117#[macro_export]
118macro_rules! tool_text_content {
119    ($e:expr) => {{
120        $crate::types::ToolResponseContent::Text($crate::types::TextContent {
121            content_type: "text".to_string(),
122            text: $e.to_string(),
123            annotations: None,
124        })
125    }};
126}
127
128/// Creates an image content object for tool responses.
129///
130/// This macro generates a `ToolResponseContent::Image` object with the provided data and MIME type.
131///
132/// # Examples
133///
134/// ```
135/// use mcp_core::tool_image_content;
136///
137/// let image_data = "base64_encoded_data".to_string();
138/// let content = tool_image_content!(image_data, "image/jpeg".to_string());
139/// ```
140#[macro_export]
141macro_rules! tool_image_content {
142    ($data:expr, $mime_type:expr) => {{
143        $crate::types::ToolResponseContent::Image($crate::types::ImageContent {
144            content_type: "image".to_string(),
145            data: $data,
146            mime_type: $mime_type,
147            annotations: None,
148        })
149    }};
150}
151
152/// Creates an audio content object for tool responses.
153///
154/// This macro generates a `ToolResponseContent::Audio` object with the provided data and MIME type.
155///
156/// # Examples
157///
158/// ```
159/// use mcp_core::tool_audio_content;
160///
161/// let audio_data = "base64_encoded_audio".to_string();
162/// let content = tool_audio_content!(audio_data, "audio/mp3".to_string());
163/// ```
164#[macro_export]
165macro_rules! tool_audio_content {
166    ($data:expr, $mime_type:expr) => {{
167        $crate::types::ToolResponseContent::Audio($crate::types::AudioContent {
168            content_type: "audio".to_string(),
169            data: $data,
170            mime_type: $mime_type,
171            annotations: None,
172        })
173    }};
174}
175
176/// Creates a resource content object for tool responses.
177///
178/// This macro generates a `ToolResponseContent::Resource` object with the provided URI and optional MIME type.
179///
180/// # Examples
181///
182/// ```
183/// use mcp_core::tool_resource_content;
184/// use url::Url;
185///
186/// let uri = Url::parse("https://example.com/resource.png").unwrap();
187/// let content = tool_resource_content!(uri, "image/png".to_string());
188/// ```
189#[macro_export]
190macro_rules! tool_resource_content {
191    ($uri:expr, $mime_type:expr) => {{
192        $crate::types::ToolResponseContent::Resource($crate::types::EmbeddedResource {
193            content_type: "resource".to_string(),
194            resource: $crate::types::ResourceContents {
195                uri: $uri,
196                mime_type: Some($mime_type),
197                text: None,
198                blob: None,
199            },
200            annotations: None,
201        })
202    }};
203    ($uri:expr) => {{
204        $crate::types::ToolResponseContent::Resource($crate::types::EmbeddedResource {
205            content_type: "resource".to_string(),
206            resource: $crate::types::ResourceContents {
207                uri: $uri,
208                mime_type: None,
209                text: None,
210                blob: None,
211            },
212            annotations: None,
213        })
214    }};
215}