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}