pulseengine_mcp_macros/
lib.rs

1//! # PulseEngine MCP Macros
2//!
3//! Procedural macros for the PulseEngine MCP Framework that dramatically simplify
4//! server and tool development while maintaining enterprise-grade capabilities.
5//!
6//! ## Quick Start
7//!
8//! Create a simple MCP server with tools:
9//!
10//! ```rust,ignore
11//! use pulseengine_mcp_macros::{mcp_server, mcp_tool};
12//!
13//! #[mcp_server(name = "Hello World")]
14//! struct HelloWorld;
15//!
16//! #[mcp_tool]
17//! impl HelloWorld {
18//!     /// Say hello to someone
19//!     async fn say_hello(&self, name: String) -> String {
20//!         format!("Hello, {}!", name)
21//!     }
22//! }
23//! ```
24//!
25//! ## Features
26//!
27//! - **Zero Boilerplate**: Focus on business logic, not protocol details
28//! - **Type Safety**: Compile-time validation of tool definitions
29//! - **Auto Schema Generation**: JSON schemas derived from Rust types
30//! - **Doc Comments**: Function documentation becomes tool descriptions
31//! - **Progressive Complexity**: Start simple, add enterprise features as needed
32
33use proc_macro::TokenStream;
34
35mod mcp_backend;
36mod mcp_prompt;
37mod mcp_resource;
38mod mcp_server;
39mod mcp_tool;
40mod utils;
41
42/// Automatically generates MCP tool definitions from Rust functions.
43///
44/// This macro transforms regular Rust functions into MCP tools with automatic
45/// JSON schema generation, parameter validation, and error handling.
46///
47/// # Basic Usage
48///
49/// ```rust,ignore
50/// use pulseengine_mcp_macros::mcp_tool;
51///
52/// #[mcp_tool]
53/// async fn say_hello(name: String) -> String {
54///     format!("Hello, {}!", name)
55/// }
56/// ```
57///
58/// # With Custom Description
59///
60/// ```rust,ignore
61/// #[mcp_tool(description = "Say hello to someone or something")]
62/// async fn say_hello(name: String, greeting: Option<String>) -> String {
63///     format!("{}, {}!", greeting.unwrap_or("Hello"), name)
64/// }
65/// ```
66///
67/// # Parameters
68///
69/// - `description`: Optional custom description (defaults to doc comments)
70/// - `name`: Optional custom tool name (defaults to function name)
71///
72/// # Features
73///
74/// - **Automatic Schema**: JSON schemas generated from Rust parameter types
75/// - **Doc Comments**: Function documentation becomes tool description
76/// - **Type Safety**: Compile-time validation of parameters
77/// - **Error Handling**: Automatic conversion of Result types
78/// - **Async Support**: Both sync and async functions supported
79#[proc_macro_attribute]
80pub fn mcp_tool(attr: TokenStream, item: TokenStream) -> TokenStream {
81    mcp_tool::mcp_tool_impl(attr.into(), item.into())
82        .unwrap_or_else(|err| err.to_compile_error())
83        .into()
84}
85
86/// Auto-implements the McpBackend trait with smart defaults.
87///
88/// This macro generates a complete McpBackend implementation with minimal
89/// configuration required. It inspects the struct and automatically generates
90/// appropriate server info, capabilities, and default implementations.
91///
92/// # Basic Usage
93///
94/// ```rust,ignore
95/// use pulseengine_mcp_macros::mcp_backend;
96///
97/// #[mcp_backend(name = "My Server")]
98/// struct MyBackend {
99///     data: String,
100/// }
101/// ```
102///
103/// # Parameters
104///
105/// - `name`: Server name (required)
106/// - `version`: Server version (defaults to Cargo package version)
107/// - `description`: Server description (defaults to doc comments)
108/// - `capabilities`: Custom capabilities (auto-detected by default)
109///
110/// # Features
111///
112/// - **Smart Capabilities**: Auto-detects capabilities from available tools
113/// - **Default Implementations**: Provides sensible defaults for all methods
114/// - **Error Handling**: Automatic error type conversion
115/// - **Version Integration**: Uses Cargo.toml version by default
116#[proc_macro_attribute]
117pub fn mcp_backend(attr: TokenStream, item: TokenStream) -> TokenStream {
118    mcp_backend::mcp_backend_impl(attr.into(), item.into())
119        .unwrap_or_else(|err| err.to_compile_error())
120        .into()
121}
122
123/// Complete server generation from a simple struct.
124///
125/// This macro combines `#[mcp_backend]` with additional server lifecycle
126/// management, providing a complete MCP server implementation.
127///
128/// # Basic Usage
129///
130/// ```rust,ignore
131/// use pulseengine_mcp_macros::mcp_server;
132///
133/// #[mcp_server(name = "Hello World")]
134/// struct HelloWorld;
135/// ```
136///
137/// # With Configuration
138///
139/// ```rust,ignore
140/// #[mcp_server(
141///     name = "Advanced Server",
142///     version = "1.0.0",
143///     description = "A more advanced MCP server"
144/// )]
145/// struct AdvancedServer {
146///     config: MyConfig,
147/// }
148/// ```
149///
150/// # Parameters
151///
152/// - `name`: Server name (required)
153/// - `version`: Server version (defaults to Cargo package version)
154/// - `description`: Server description (defaults to doc comments)
155/// - `transport`: Default transport type (defaults to auto-detect)
156///
157/// # Features
158///
159/// - **Complete Implementation**: Backend + server management
160/// - **Fluent Builder**: Provides `.serve_*()` methods
161/// - **Transport Auto-Detection**: Smart defaults based on environment
162/// - **Configuration Integration**: Works with PulseEngine config system
163#[proc_macro_attribute]
164pub fn mcp_server(attr: TokenStream, item: TokenStream) -> TokenStream {
165    mcp_server::mcp_server_impl(attr.into(), item.into())
166        .unwrap_or_else(|err| err.to_compile_error())
167        .into()
168}
169
170/// Automatically generates MCP resource definitions from Rust functions.
171///
172/// This macro transforms regular Rust functions into MCP resources with automatic
173/// URI template parsing, parameter extraction, and content type handling.
174///
175/// # Basic Usage
176///
177/// ```rust,ignore
178/// use pulseengine_mcp_macros::mcp_resource;
179///
180/// #[mcp_resource(uri_template = "file://{path}")]
181/// async fn read_file(&self, path: String) -> Result<String, std::io::Error> {
182///     tokio::fs::read_to_string(&path).await
183/// }
184/// ```
185///
186/// # With Custom Configuration
187///
188/// ```rust,ignore
189/// #[mcp_resource(
190///     uri_template = "db://{database}/{table}",
191///     name = "database_table",
192///     description = "Read data from a database table",
193///     mime_type = "application/json"
194/// )]
195/// async fn read_table(&self, database: String, table: String) -> Result<serde_json::Value, Error> {
196///     // Implementation
197/// }
198/// ```
199///
200/// # Parameters
201///
202/// - `uri_template`: Required URI template with parameters in `{param}` format
203/// - `name`: Optional custom resource name (defaults to function name)
204/// - `description`: Optional custom description (defaults to doc comments)
205/// - `mime_type`: Optional MIME type (defaults to "text/plain")
206///
207/// # Features
208///
209/// - **URI Template Parsing**: Automatic extraction of parameters from URI templates
210/// - **Type Safety**: Compile-time validation of parameter types
211/// - **Auto-Documentation**: Uses function doc comments as resource descriptions
212/// - **Content Type Detection**: Automatic MIME type handling
213/// - **Error Handling**: Converts function errors to MCP protocol errors
214///
215/// # References
216///
217/// - [MCP Resources Specification](https://modelcontextprotocol.io/specification/)
218/// - [Building with LLMs Tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms)
219#[proc_macro_attribute]
220pub fn mcp_resource(attr: TokenStream, item: TokenStream) -> TokenStream {
221    mcp_resource::mcp_resource_impl(attr.into(), item.into())
222        .unwrap_or_else(|err| err.to_compile_error())
223        .into()
224}
225
226/// Automatically generates MCP prompt definitions from Rust functions.
227///
228/// This macro transforms regular Rust functions into MCP prompts with automatic
229/// argument validation and prompt message generation.
230///
231/// # Basic Usage
232///
233/// ```rust,ignore
234/// use pulseengine_mcp_macros::mcp_prompt;
235///
236/// #[mcp_prompt(name = "code_review")]
237/// async fn generate_code_review(&self, code: String, language: String) -> Result<PromptMessage, Error> {
238///     // Generate prompt for code review
239/// }
240/// ```
241///
242/// # With Custom Configuration
243///
244/// ```rust,ignore
245/// #[mcp_prompt(
246///     name = "sql_query_helper",
247///     description = "Generate SQL queries based on natural language",
248///     arguments = ["description", "table_schema", "output_format"]
249/// )]
250/// async fn sql_helper(&self, description: String, table_schema: String, output_format: String) -> Result<PromptMessage, Error> {
251///     // Implementation
252/// }
253/// ```
254///
255/// # Parameters
256///
257/// - `name`: Optional custom prompt name (defaults to function name)
258/// - `description`: Optional custom description (defaults to doc comments)
259/// - `arguments`: Optional array of argument names for documentation
260///
261/// # Features
262///
263/// - **Argument Validation**: Automatic validation of prompt arguments
264/// - **Type Safety**: Compile-time validation of parameter types
265/// - **Auto-Documentation**: Uses function doc comments as prompt descriptions
266/// - **Error Handling**: Converts function errors to MCP protocol errors
267/// - **Schema Generation**: Automatic argument schema generation
268///
269/// # References
270///
271/// - [MCP Prompts Specification](https://modelcontextprotocol.io/specification/)
272/// - [Building with LLMs Tutorial](https://modelcontextprotocol.io/tutorials/building-mcp-with-llms)
273#[proc_macro_attribute]
274pub fn mcp_prompt(attr: TokenStream, item: TokenStream) -> TokenStream {
275    mcp_prompt::mcp_prompt_impl(attr.into(), item.into())
276        .unwrap_or_else(|err| err.to_compile_error())
277        .into()
278}
279
280/// Derives MCP tool implementations for all methods in an impl block.
281///
282/// This is a convenience macro that applies `#[mcp_tool]` to all public
283/// methods in an impl block.
284///
285/// # Usage
286///
287/// ```rust,ignore
288/// use pulseengine_mcp_macros::mcp_tools;
289///
290/// #[mcp_tools]
291/// impl MyServer {
292///     /// This becomes an MCP tool
293///     async fn tool_one(&self, param: String) -> String {
294///         param.to_uppercase()
295///     }
296///
297///     /// This also becomes an MCP tool
298///     fn tool_two(&self, x: i32, y: i32) -> i32 {
299///         x + y
300///     }
301///
302///     // Private methods are ignored
303///     fn helper_method(&self) -> bool {
304///         true
305///     }
306/// }
307/// ```
308#[proc_macro_attribute]
309pub fn mcp_tools(attr: TokenStream, item: TokenStream) -> TokenStream {
310    mcp_tool::mcp_tools_impl(attr.into(), item.into())
311        .unwrap_or_else(|err| err.to_compile_error())
312        .into()
313}
pulseengine_mcp_macros/lib.rs

pulseengine_mcp_macros/
lib.rs
